feat: implement evidence-based routing audit workflows with explicit intent confirmation, risk scoring, and cleanup plan gating

Author: thunderdew-dawn

agent-docs/machine/architecture-governance.snapshot.json

@@ -2,7 +2,7 @@
   "snapshot_version": 1,
   "as_of": "2026-07-02",
   "status": "governed",
-  "governance_note": "Updated for Low-End Analysis evidence levels 1-5, additive audio-feature metrics, rendered-master proxy-only claims, role-confirmed stem/bus gates for stem-specific conclusions, and declared manual/forbidden low-end workflow actions. Persistent-write safety posture is unchanged; FL Studio render automation, automatic project writes, plugin loading, and stem-specific claims from master-only audio remain forbidden.",
+  "governance_note": "Updated for Routing Audit evidence levels, finding states, producer intent confirmation, meter-proxy labeling, cleanup-plan gating, and Mix Review evidence-weighted scoring with rendered-master proxy and role-confirmed stem evidence. Persistent-write safety posture is unchanged; Routing Audit and Mix Review remain read-only, planning remains confirmation-gated, and apply remains separate with explicit approval and rollback.",
   "project": {
     "name": "fls-pilot",
     "package_version": "3.0.0b3",
@@ -351,6 +351,32 @@
     "audio_features_contract": "fls-pilot.audio-features.v1",
     "audio_artifact_contract": "fls-pilot.audio-artifact.v1",
     "evidence_link_contract": "fls-pilot.evidence-link.v1",
+    "mix_review_contract": {
+      "evidence_levels": {
+        "1": "static_project_metadata",
+        "2": "live_meter_window",
+        "3": "rendered_master_audio_proxy",
+        "4": "role_confirmed_stem_or_bus_audio"
+      },
+      "finding_states": [
+        "static_heuristic",
+        "name_based_unconfirmed",
+        "metadata_suspected",
+        "live_meter_supported",
+        "rendered_master_proxy",
+        "stem_audio_confirmed",
+        "accepted_by_user",
+        "rejected_by_user",
+        "ignored_by_user",
+        "requires_more_evidence"
+      ],
+      "score_model": "risk_score_v2 uses severity, evidence confidence, rule/profile weight, and user decision modifiers while preserving legacy_score metadata.",
+      "rendered_master_claim_limit": "proxy_only_no_stem_specific_causes",
+      "stem_specific_claims_require": "role_confirmed_stem_or_bus_audio",
+      "automatic_fl_render": false,
+      "persistent_writes": false,
+      "fix_plan_gating": "blocked_or_draft_until_sufficient_evidence_and_user_approval"
+    },
     "low_end_contract": {
       "evidence_levels": {
         "1": "static_metadata",

agent-docs/machine/architecture/analysis-workflows.snapshot.json

@@ -5,7 +5,7 @@
   "source_snapshot": "agent-docs/machine/architecture-analysis.snapshot.json",
   "source_snapshot_sha256": "ff0d38588b91510a3073e81d885de38f9116cddfbcd95686cbf11c28a6db8d7f",
   "generated_at": "2026-07-02",
-  "note": "Scoped slice refreshed for Low-End Analysis evidence levels 1-5, proxy rendered-master semantics, workflow action declarations, and Control Center metadata; full static architecture analysis was not regenerated.",
+  "note": "Scoped slice refreshed for Routing Audit evidence levels, finding states, cleanup-plan gating metadata, and Mix Review evidence-weighted scoring/rendered-audio evidence metadata; full static architecture analysis was not regenerated.",
   "load_when": [
     "workflow registry, report schema, scoring, evidence, freshness, prerequisites, or health aggregation changes",
     "Control Center project-review workflow panel ownership or endpoint changes",
@@ -155,6 +155,16 @@
               "evidence_mode": "live_runtime",
               "invalidates_on": [],
               "ttl_seconds": 2
+            },
+            {
+              "id": "rendered_stem_features",
+              "observation_kind": "rendered_stem_features",
+              "required": false,
+              "evidence_mode": "rendered_audio",
+              "invalidates_on": [
+                "project_identity_change",
+                "audio_source_hash_changed"
+              ]
             }
           ]
         },
@@ -163,17 +173,23 @@
         "group": "Project Review",
         "endpoint": "/api/workflows/mix-review",
         "action_label": "Run Mix Review",
-        "safety_note": "Read-only mixer review. Level 1 is static; Level 2 uses optional transient playback/watch evidence; Level 3/4 audio evidence is prepared for external analyzer integration.",
+        "safety_note": "Read-only mixer review. Level 1 is static; Level 2 uses optional transient playback/watch evidence; Level 3 uses linked rendered master proxy evidence; Level 4 uses role-confirmed stem/bus evidence.",
         "supported_next_actions": [
           "run_static_review",
           "start_level_2_watch",
           "link_rendered_master_evidence",
-          "link_stem_bus_evidence"
+          "link_stem_bus_evidence",
+          "confirm_mix_review_finding",
+          "accept_mix_review_finding",
+          "reject_mix_review_finding",
+          "ignore_mix_review_finding"
         ],
         "manual_only_actions": [
           "choose_loudest_section",
           "manual_audio_render",
-          "manual_stem_export"
+          "manual_stem_export",
+          "confirm_track_roles",
+          "approve_fix_plan"
         ],
         "forbidden_actions": [
           "automatic_render",
@@ -182,15 +198,56 @@
         ],
         "metadata": {
           "mix_review_levels": [
-            "level_1_static",
-            "level_2_live_peak_watch",
-            "level_3_rendered_master_placeholder",
-            "level_4_stem_bus_placeholder"
+            "level_1_static_project_metadata",
+            "level_2_live_meter_window",
+            "level_3_rendered_master_audio_proxy",
+            "level_4_role_confirmed_stem_bus_audio"
+          ],
+          "finding_states": [
+            "static_heuristic",
+            "name_based_unconfirmed",
+            "metadata_suspected",
+            "live_meter_supported",
+            "rendered_master_proxy",
+            "stem_audio_confirmed",
+            "accepted_by_user",
+            "rejected_by_user",
+            "ignored_by_user",
+            "requires_more_evidence"
+          ],
+          "score_fields": [
+            "legacy_score",
+            "risk_score_v2",
+            "score_status",
+            "score_inputs",
+            "evidence_weight",
+            "decision_adjusted_score",
+            "blocked_findings_count",
+            "provisional_findings_count",
+            "confirmed_findings_count"
+          ],
+          "fix_plan_statuses": [
+            "blocked",
+            "draft",
+            "requires_user_approval",
+            "approved",
+            "not_applicable"
           ],
-          "external_audio_analyzer_status": "not_merged_yet",
           "genre_profiles": [
             "default",
-            "psytrance"
+            "psytrance",
+            "techno",
+            "hiphop",
+            "ambient",
+            "rock",
+            "cinematic"
+          ],
+          "target_contexts": [
+            "streaming",
+            "club",
+            "festival",
+            "demo",
+            "unknown"
           ]
         }
       },
@@ -208,11 +265,50 @@
         "group": "Project Review",
         "endpoint": "/api/workflows/routing-audit",
         "action_label": "Run Routing Audit",
-        "safety_note": "Read-only routing audit. Cleanup remains proposal-first.",
-        "supported_next_actions": [],
-        "manual_only_actions": [],
-        "forbidden_actions": [],
-        "metadata": {}
+        "safety_note": "Read-only routing audit. Static and meter findings remain evidence-labeled; cleanup remains proposal-first and confirmation-gated.",
+        "supported_next_actions": [
+          "run_static_routing_snapshot",
+          "run_meter_snapshot_proxy",
+          "confirm_template_profile",
+          "confirm_track_roles",
+          "plan_cleanup_after_confirmation"
+        ],
+        "manual_only_actions": [
+          "confirm_direct_to_master_intent",
+          "confirm_reference_monitor_only",
+          "confirm_sidechain_control_not_audible",
+          "approve_cleanup_plan"
+        ],
+        "forbidden_actions": [
+          "automatic_routing_cleanup",
+          "playlist_clip_editing",
+          "plugin_loading",
+          "automatic_render"
+        ],
+        "metadata": {
+          "routing_evidence_levels": [
+            "static_routing_snapshot",
+            "meter_snapshot_proxy",
+            "user_confirmed_routing_intent",
+            "verified_cleanup_readback"
+          ],
+          "plan_gating_statuses": [
+            "blocked_requires_confirmation",
+            "draft_proxy_evidence",
+            "ready_for_user_approval",
+            "no_actionable_findings"
+          ],
+          "intent_profiles": [
+            "default",
+            "psytrance_stem_bus_template",
+            "mixdown_premaster_template",
+            "recording_session",
+            "sound_design_session",
+            "live_performance",
+            "minimal_sketch",
+            "reference_monitoring"
+          ]
+        }
       },
       {
         "id": "low_end_analysis",

agent-docs/machine/architecture/mcp-surface.snapshot.json

@@ -4,8 +4,8 @@
   "title": "MCP tools, resources, prompts and public tool safety summary",
   "source_snapshot": "agent-docs/machine/architecture-analysis.snapshot.json",
   "source_snapshot_sha256": "ff0d38588b91510a3073e81d885de38f9116cddfbcd95686cbf11c28a6db8d7f",
-  "generated_at": "2026-06-19",
-  "note": "Slim generated MCP surface slice. For a concrete tool module, load the matching file under architecture/mcp-tools/.",
+  "generated_at": "2026-07-02",
+  "note": "Slim MCP surface slice refreshed for additive Routing Audit cleanup-plan gating arguments and behavior. Tool counts and safety-class totals are unchanged; for concrete tool details, load the matching file under architecture/mcp-tools/.",
   "load_when": [
     "MCP tools, resources, or prompts are added, removed, renamed, or changed",
     "public MCP behavior, safety annotations, or tool registration changes",

agent-docs/machine/architecture/mcp-tools/routing.snapshot.json

@@ -4,7 +4,7 @@
   "title": "MCP tool module: routing",
   "source_snapshot": "agent-docs/machine/architecture-analysis.snapshot.json",
   "source_snapshot_sha256": "ff0d38588b91510a3073e81d885de38f9116cddfbcd95686cbf11c28a6db8d7f",
-  "generated_at": "2026-07-01",
+  "generated_at": "2026-07-02",
   "load_when": [
     "MCP tool implementation or registration changes in the routing tool module",
     "safety annotations, doc safety, destructive hints, or protocol usage change for routing tools"
@@ -17,15 +17,15 @@
       "write-safe-required": 4
     },
     "destructive_hint_true_count": 0,
-    "first_line": 269
+    "first_line": 272
   },
   "tools": [
     {
       "contract_safety_class": "read-only",
       "destructive_hint": null,
       "evidence": "annotation readOnlyHint=True destructiveHint=None; protocol=CMD_MIXER_GET_ROUTING; safetyClass='read-only'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 269,
+      "line": 272,
       "name": "fl_get_routing",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": true,
@@ -38,7 +38,7 @@
       "destructive_hint": null,
       "evidence": "annotation readOnlyHint=True destructiveHint=None; protocol=CMD_MIXER_GET_ROUTING_ALL; safetyClass='read-only'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 280,
+      "line": 283,
       "name": "fl_get_routing_all",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": true,
@@ -51,7 +51,7 @@
       "destructive_hint": null,
       "evidence": "annotation readOnlyHint=True destructiveHint=None; protocol=CMD_CHANNEL_ROUTING_SUMMARY; safetyClass='read-only'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 289,
+      "line": 292,
       "name": "fl_get_channel_routing",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": true,
@@ -64,7 +64,7 @@
       "destructive_hint": null,
       "evidence": "annotation readOnlyHint=True destructiveHint=None; protocol=CMD_CHANNEL_ROUTING_SUMMARY,CMD_MIXER_GET_ROUTING_ALL,CMD_PLUGIN_LIST; helper_calls=detect_cleanup; safetyClass='read-only'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 298,
+      "line": 301,
       "name": "fl_detect_cleanup_candidates",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": true,
@@ -77,7 +77,7 @@
       "destructive_hint": false,
       "evidence": "annotation readOnlyHint=False destructiveHint=False; protocol=CMD_MIXER_SET_ROUTE; uses safety layer; safetyClass='write-safe-required'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 308,
+      "line": 311,
       "name": "fl_set_route",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": false,
@@ -90,7 +90,7 @@
       "destructive_hint": false,
       "evidence": "annotation readOnlyHint=False destructiveHint=False; uses safety layer; helper_calls=_bus_rename_entry,_dry_run_report,_no_write_report,_route_write_entry; safetyClass='write-safe-required'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 337,
+      "line": 340,
       "name": "fl_group_tracks",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": false,
@@ -101,9 +101,9 @@
     {
       "contract_safety_class": "read-only",
       "destructive_hint": null,
-      "evidence": "annotation readOnlyHint=True destructiveHint=None; protocol=CMD_CHANNEL_LIST,CMD_MIXER_GET_ALL_PEAKS; helper_calls=routing_audit_options_from_inputs,merge_channel_control_rows,capture_signal_flow_evidence,template_compliance_result,level_2_signal_findings,_routing_review_findings; public_args=routing_check_mode,template_compliance,selected_template_profile; safetyClass='read-only'; doc_safety=True",
+      "evidence": "annotation readOnlyHint=True destructiveHint=None; protocol=CMD_CHANNEL_LIST,CMD_MIXER_GET_ALL_PEAKS; helper_calls=routing_audit_options_from_inputs,merge_channel_control_rows,capture_signal_flow_evidence,template_compliance_result,level_2_signal_findings,enrich_routing_findings,routing_cleanup_plan_gating,_routing_review_findings; public_args=routing_check_mode,template_compliance,selected_template_profile; safetyClass='read-only'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 446,
+      "line": 449,
       "name": "fl_review_routing",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": true,
@@ -114,9 +114,9 @@
     {
       "contract_safety_class": "read-only",
       "destructive_hint": null,
-      "evidence": "annotation readOnlyHint=True destructiveHint=None; safetyClass='read-only'; doc_safety=True",
+      "evidence": "annotation readOnlyHint=True destructiveHint=None; helper_calls=enrich_routing_findings,routing_cleanup_plan_gating; public_args=issues,proposed_buses,source_findings,user_decisions; safetyClass='read-only'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 697,
+      "line": 744,
       "name": "fl_plan_routing_cleanup",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": true,
@@ -129,7 +129,7 @@
       "destructive_hint": false,
       "evidence": "annotation readOnlyHint=False destructiveHint=False; uses safety layer; helper_calls=_bus_rename_entry,_dry_run_report,_no_write_report,_route_write_entry; safetyClass='write-safe-required'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 772,
+      "line": 884,
       "name": "fl_apply_routing_cleanup",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": false,
@@ -142,7 +142,7 @@
       "destructive_hint": false,
       "evidence": "annotation readOnlyHint=False destructiveHint=False; uses safety layer; helper_calls=_bus_rename_entry,_dry_run_report,_no_write_report,_route_write_entry; safetyClass='write-safe-required'; doc_safety=True",
       "has_safety_doc": true,
-      "line": 871,
+      "line": 983,
       "name": "fl_apply_bus_layout",
       "path": "src/fls_pilot/tools/routing.py",
       "read_only_hint": false,

evals/evals.json

@@ -218,6 +218,8 @@
         "fl_review_mix without args remains Level 1 static and does not start playback",
         "use explicit Level 2 watch evidence before treating peaks, clipping, or headroom as live evidence",
         "distinguish static snapshot findings from live peak-watch evidence",
+        "show finding_state, score_status, and whether each fix plan is blocked, draft, or requires approval",
+        "do not score rejected findings negatively or include ignored findings in fix plans",
         "do not apply trims/EQ/compression without explicit approval",
         "report limitations when rendered audio evidence is missing",
         "do not claim Level 3 or Level 4 rendered audio analysis unless external analyzer evidence is linked"
@@ -256,7 +258,9 @@
         "show Level 3 expected master checks without claiming LUFS, true peak, clipping count, spectrum, or stereo facts",
         "show Level 4 expected stem checks without claiming masking, phase, or bus-balance facts",
         "mark external analyzer integration as pending when no artifact evidence is available",
-        "do not create fake rendered-audio findings inside Mix Review"
+        "do not create rendered-audio findings without linked artifact evidence",
+        "when rendered master evidence is linked, keep findings proxy-labeled and avoid stem-specific causal claims",
+        "when stem evidence is linked, require confirmed roles before stem-specific findings"
       ],
       "not_expected_tools": [
         "automatic FL render",
@@ -345,6 +349,8 @@
         "read-only routing diagnosis and planning",
         "do not alter sends/routes or names",
         "include explicit approval gate for any later cleanup batch",
+        "label static routing suspicions and name/template-based findings as confirmation-gated",
+        "block cleanup-plan readiness until routing findings and producer intent are confirmed",
         "never propose routing Master as a normal source target",
         "do not suppress cleanup findings when template profile classification is ambiguous"
       ],
@@ -357,6 +363,7 @@
       "success_criteria": [
         "assistant separates route findings from rollback-safe proposed actions",
         "cleanup plan references supported routing tools only",
+        "assistant reports routing evidence level, finding state, and cleanup-plan gating status",
         "assistant treats ambiguous template profile matches as validation-needed rather than cleanup-safe suppressions"
       ]
     },
@@ -383,6 +390,7 @@
         "read-only routing diagnosis only",
         "do not start playback when the user chose manual playback",
         "report static_snapshot_plus_meter_snapshot evidence and whether signal-flow evidence was available",
+        "label meter findings as proxy evidence rather than proof of wrong routing or musical intent",
         "do not apply routing cleanup, bus layout, naming, coloring, or send changes"
       ],
       "not_expected_tools": [
@@ -396,7 +404,7 @@
         "assistant selects the Level 2 routing mode instead of the default static audit",
         "assistant uses the selected psytrance profile rather than hard-coded genre rules",
         "assistant treats Channel Rack versus Mixer differences as review findings unless signal evidence strengthens them",
-        "assistant labels signal-confirmed template findings only when live meter evidence is present",
+        "assistant labels signal-active template findings as meter-snapshot proxy evidence only when live meter evidence is present",
         "assistant offers Level 1 fallback if signal-flow evidence is unavailable"
       ]
     },