fix(truncation): gate diagnostic file; strengthen FDR/score tests

- TruncationSearchTask: write CandidateRanks.tsv only when PerfLogPath is set,
  register it via FinishedWritingFile, and wrap it best-effort so a diagnostic
  write can't abort the task (#14). Document the intentional PEP==0 disk-filter
  guard and the in-memory-only PepQWasUsed metric (#11, #15 -- wontfix).
- TruncationSearchEngineTests: ScanS7 now asserts the opposing-series peaks
  neither raise the score nor change the integer matched-ion count, so the test
  distinguishes "ignored" from merely "harmless" (#17).
- TruncationFdrAndOutputTests: PepRuns pins the skipped-PEP branch (PEP_QValue
  == 2 on a too-small pool) rather than only asserting no throw (#18).

Addresses findings #14, #17, #18 and documents #11/#15 from the PR #2666 review.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DWZ1KbGenS4w1beTMXWgek

Author: trishorts

MetaMorpheus/TaskLayer/TruncationSearchTask/TruncationSearchTask.cs

@@ -230,9 +230,23 @@ protected override MyTaskResults RunSpecific(string OutputFolder, List<DbForTask
             WriteOutputs(withFdr, OutputFolder, taskId);
 
             // Diagnostic side file: per-scan winning-parent rank in the index match-count ordering.
-            string ranksPath = Path.Combine(OutputFolder, "CandidateRanks.tsv");
-            File.WriteAllLines(ranksPath,
-                new[] { "File\tScanNumber\tCandidateRank\tCandidatePoolSize\tScore\tProducedTruncation" }.Concat(winnerRankRows));
+            // Opt-in (gated on the same PerfLogPath that enables benchmarking), registered via
+            // FinishedWritingFile, and best-effort so a diagnostic-write failure can't abort an otherwise
+            // successful task (#14).
+            if (!string.IsNullOrWhiteSpace(TruncationSearchParameters.PerfLogPath))
+            {
+                try
+                {
+                    string ranksPath = Path.Combine(OutputFolder, "CandidateRanks.tsv");
+                    File.WriteAllLines(ranksPath,
+                        new[] { "File\tScanNumber\tCandidateRank\tCandidatePoolSize\tScore\tProducedTruncation" }.Concat(winnerRankRows));
+                    FinishedWritingFile(ranksPath, new List<string> { taskId });
+                }
+                catch (Exception ex)
+                {
+                    Warn($"Could not write diagnostic CandidateRanks.tsv: {ex.Message}");
+                }
+            }
 
             // 6. Optional perf-log row (03_Benchmarks). No-op unless a path is configured.
             if (!string.IsNullOrWhiteSpace(TruncationSearchParameters.PerfLogPath))
@@ -362,6 +376,8 @@ private List<TruncationParent> BuildParentsFromPsms(IEnumerable<SpectralMatch> p
                 }
 
                 // Record whether the PEP q-value (vs notch q-value) drove inclusion (perf logging).
+                // By design this reflects the in-memory parent path only; the disk/db-seeded paths leave the
+                // metric false because PsmFromTsv's PEP column is ambiguous there (#15, intentional).
                 FdrInfo fdr = psm.GetFdrInfo(peptideLevel: true) ?? psm.GetFdrInfo(peptideLevel: false);
                 if (fdr != null && fdr.PEP_QValue != 2)
                 {
@@ -573,6 +589,11 @@ private List<TruncationParent> BuildParentsFromDisk()
         /// <summary>Permissive parent filter (#3) for disk rows (PsmFromTsv stores PEP_QValue/QValueNotch).</summary>
         private static bool PassesDiskParentFilter(PsmFromTsv row, double threshold)
         {
+            // 0 is treated as "PEP not computed" alongside the 2 sentinel ON PURPOSE for disk rows:
+            // PsmFromTsv defaults an absent/empty PEP_QValue column to 0, so a disk 0 is ambiguous (absent
+            // column vs a genuine best-possible 0.0) and the two cannot be told apart here. Falling back to
+            // the notch q-value when PEP==0 is the safe choice. Do NOT "simplify" this to `!= 2` only -- that
+            // would pass absent-PEP rows as if q=0 (reviewed: findings #11/#15, intentional wontfix).
             if (row.PEP_QValue != 0 && row.PEP_QValue != 2)
             {
                 return row.PEP_QValue <= threshold;

MetaMorpheus/Test/TruncationFdrAndOutputTests.cs

@@ -79,6 +79,11 @@ public void PepRuns_OrSkipsCleanly_OnSmallPool()
                 new List<(string, CommonParameters)> { ("synthetic", _cp) }, "TruncationTask", doPep: true));
 
             Assert.That(result.All(p => p.FdrInfo.QValue >= 0 && p.FdrInfo.QValue <= 1), Is.True);
+
+            // Pin the branch, not just absence-of-throw: a 2-PSM pool can't train PEP, so PEP must be
+            // SKIPPED -- every row keeps the "PEP not computed" sentinel (PEP_QValue == 2), rather than
+            // silently emitting an untrained PEP q-value (#18).
+            Assert.That(result.All(p => p.FdrInfo.PEP_QValue == 2), Is.True);
         }
 
         [Test]

MetaMorpheus/Test/TruncationSearchEngineTests.cs

@@ -214,6 +214,15 @@ public void ScanS7_OpposingIonsIgnored()
             Assert.That(s7.Outcome, Is.EqualTo(TruncationScanOutcome.Winner));
             Assert.That(s7.WinningParent.ProteinAccession, Is.EqualTo("P1"));
             Assert.That(s7.WinningSeries, Is.EqualTo(FragmentationTerminus.N));
+
+            // The opposing-series peaks must not be MATCHED: they can only dilute the intensity-normalized
+            // score (they enlarge the total-intensity denominator), never raise it, and must not change the
+            // integer matched-ion count -- i.e. the score moves by less than one ion. (Verified empirically:
+            // exact equality fails because the two extra peaks shift the normalization by ~0.05; a matched
+            // opposing ion would instead RAISE the score by ~1.) (#17)
+            var s2 = _results[1];
+            Assert.That(s7.Score, Is.LessThanOrEqualTo(s2.Score));
+            Assert.That(s2.Score - s7.Score, Is.LessThan(1.0));
         }
 
         [Test]