tonepath-dj

name	tonepath-dj
description	Audit Tonepath music-state paths using local evidence, optional web search, and strict source-grounded decisions. Use when reviewing Tonepath eval audit evidence, deciding keep/demote/reject for tracks, or explaining music fit without inventing audio facts.

Tonepath DJ Audit

Use this skill to audit a Tonepath evidence pack. Tonepath remains the source of local facts; your job is to judge fit for the user's state transition.

Workflow

1. Read the evidence pack JSON path supplied by the user.
2. Review the field semantics and threshold guide below before judging candidates.
3. Review each candidate's local evidence: title, artist, album, phase, score, confidence, BPM, loudness, energy, vocalness, selector reasons, red flags, and yellow flags.
4. If web search is enabled, search only for the candidate title + artist + album. Use web evidence to identify context such as OST, vocal song, showpiece, ambient, game soundtrack, or lyrical/mood mismatch.
5. Decide keep, demote, or reject for each candidate.
6. Return JSON only, matching schemas/audit-output.schema.json.

Evidence Field Semantics

The evidence pack is generated by Tonepath before Codex runs. Treat it as the source of local facts.

• prompt: the user's original listening request.
• source_state / target_state: normalized state-transition endpoints inferred by Tonepath.
• constraints: hard user constraints such as avoid_vocals.
• phase: the path segment for the candidate, for example decompress, stabilize, focus, soften, settle, or calm.
• score: Tonepath selector's relative score for this run. It is useful for comparing candidates in the same evidence pack, not an absolute music quality score.
• confidence: Tonepath candidate confidence. High confidence means local evidence is available; it does not guarantee the recommendation is good.
• features.source: where audio features came from, for example model-essentia-voice-instrumental.
• features.confidence: confidence in the feature extraction result.
• features.energy: approximate 0..1 local stimulation/energy estimate. Higher means more intense.
• features.loudness: approximate loudness in dBFS. Values closer to 0 are louder; lower negative values are quieter.
• features.bpm: local tempo estimate. It can conflict with web metadata; cite both if conflict matters.
• features.vocalness: approximate 0..1 local voice/vocal estimate. Higher means more likely vocal-heavy.
• reasons: Tonepath selector's local reasons. Cite them as local evidence; do not turn them into new facts.
• red_flags / yellow_flags: Tonepath's local quality warnings. Red flags are serious; yellow flags need caution.

Threshold Guide

Use these as review heuristics, not as absolute truth.

• For avoid_vocals, vocalness <= 0.35 supports no-vocals; 0.35..0.65 is inconclusive; >= 0.65 is a vocal risk.
• For focus, decompress, calm, soften, and low-stim phases, BPM >= 140 is a stimulation risk.
• For focus, decompress, calm, soften, and low-stim phases, energy >= 0.68 is a stimulation risk.
• For focus, decompress, calm, soften, and low-stim phases, loudness >= -9.0 is a loudness risk.
• Low vocalness does not automatically mean good fit. A low-vocal showpiece, virtuoso piano track, fast rhythm game song, or meme/challenge piece can still be distracting.
• Web evidence can clarify identity and context, but it must not overwrite local audio facts. If web and local facts conflict, mention the conflict and lower fit_score.

Grounding Rules

• Do not invent BPM, loudness, energy, vocalness, genre, mood, lyrics, instrumentation, or popularity.
• Treat local audio facts as local evidence, not absolute truth.
• Treat web results as context evidence and cite URLs.
• Separate local and web evidence in evidence_used.
• If evidence is weak or conflicting, lower fit_score and explain the uncertainty.
• Do not play audio, modify SQLite, modify files, start Tonepath playback, or write profile rules.

Rubric

• keep: fits the phase and user constraints with no serious evidence conflict.
• demote: usable but less suitable than stronger candidates.
• reject: conflicts with the prompt or phase enough that it should not be in the path.

Common review labels:

• instrumental but overstimulating: low vocalness, but high BPM, virtuoso/showpiece context, or otherwise distracting.
• vocal-heavy in low-stim prompt: high vocalness or web evidence of vocals in a calm/focus/low-stim request.
• weak evidence: important fields are missing or low-confidence.
• context mismatch: web evidence suggests a mood/style that does not fit the transition.

For "no vocals" requests, prefer low-vocal instrumental or ambient/OST evidence. For focus/decompress, penalize high stimulation even when the track is instrumental.

Input Example

Example evidence candidate:

{
  "phase": "focus",
  "track": {
    "id": 34,
    "title": "Rush E",
    "artist": "Toms Mucenieks",
    "album": "Rush E"
  },
  "score": 3.761,
  "confidence": "high",
  "features": {
    "source": "model-essentia-voice-instrumental",
    "confidence": "high",
    "energy": 0.556,
    "loudness": -13.32,
    "bpm": 143.5,
    "vocalness": 0.141
  },
  "reasons": [
    "vocalness feature supports no-vocals constraint",
    "phase stimulation penalty adjusted the score"
  ],
  "red_flags": [],
  "yellow_flags": []
}

Interpretation: local vocalness supports avoid_vocals, but BPM is high for focus/decompress and web context may identify this as a distracting showpiece.

Output Examples

Keep example:

{
  "track_id": 23,
  "decision": "keep",
  "fit_score": 0.84,
  "risk_flags": [],
  "reason": "Local energy, BPM, loudness, and vocalness fit the decompression phase and no-vocals constraint.",
  "evidence_used": [
    {"type": "local", "field": "phase", "value": "decompress", "url": null, "note": "Candidate is assigned to decompression."},
    {"type": "local", "field": "features.vocalness", "value": 0.285, "url": null, "note": "Local vocalness supports avoid_vocals."},
    {"type": "web", "field": "release_context", "value": "Original soundtrack", "url": "https://example.com/source", "note": "Web source confirms soundtrack context."}
  ]
}

Demote example:

{
  "track_id": 22,
  "decision": "demote",
  "fit_score": 0.53,
  "risk_flags": ["instrumental but overstimulating", "high BPM for decompress"],
  "reason": "Local vocalness fits avoid_vocals, but BPM is high for a decompression step from irritation.",
  "evidence_used": [
    {"type": "local", "field": "features.vocalness", "value": 0.344, "url": null, "note": "Local vocalness is low enough for avoid_vocals."},
    {"type": "local", "field": "features.bpm", "value": 139.8, "url": null, "note": "Near the high-stimulation threshold for decompression."}
  ]
}

Reject example:

{
  "track_id": 12,
  "decision": "reject",
  "fit_score": 0.08,
  "risk_flags": ["vocal-heavy in low-stim prompt", "high energy for calm/focus"],
  "reason": "Local vocalness and energy conflict with the no-vocals focus request, and web evidence identifies lyric-bearing song context.",
  "evidence_used": [
    {"type": "local", "field": "features.vocalness", "value": 0.616, "url": null, "note": "Local vocalness is inconclusive to high for no-vocals."},
    {"type": "local", "field": "features.energy", "value": 0.687, "url": null, "note": "Local energy is high for focus."},
    {"type": "web", "field": "lyrics_context", "value": "lyrics page", "url": "https://example.com/lyrics", "note": "Web source indicates lyric-bearing song context."}
  ]
}