@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/coverage-analysis/references/guidelines.md

@@ -0,0 +1,68 @@
+# Explicit Risk/CRAP Analysis
+
+Read this file only when the user explicitly asks for project-wide risk
+hotspots, CRAP scores, complexity-weighted priorities, or refactoring safety.
+Do not read it for supplied-excerpt interpretation, plateau diagnosis, or target
+arithmetic alone.
+
+## Compute the risk data
+
+Resolve the scripts relative to this skill's `SKILL.md`:
+
+```powershell
+& "<skill-directory>/scripts/Compute-CrapScores.ps1" `
+    -CoberturaPath @(<all Cobertura paths>) `
+    -CrapThreshold <crap_threshold> `
+    -TopN <top_n>
+
+& "<skill-directory>/scripts/Extract-MethodCoverage.ps1" `
+    -CoberturaPath @(<all Cobertura paths>) `
+    -CoverageThreshold <line_threshold> `
+    -BranchThreshold <branch_threshold> `
+    -Filter below-threshold
+```
+
+`Compute-CrapScores.ps1` emits aggregate line/branch coverage, method counts,
+flagged counts, and sorted hotspots. `Extract-MethodCoverage.ps1` emits every
+below-threshold method. Use both for explicit project-wide risk work.
+
+CRAP is:
+
+`CRAP(m) = complexity² × (1 − lineCoverage)³ + complexity`
+
+A method at 100% coverage therefore has CRAP equal to its complexity. Use 30 as
+the default flagged threshold; treat 15–30 as moderate rather than catastrophic.
+
+## Scale the output
+
+- Show the top 3 actual risk hotspots by default.
+- Exclude fully covered low-risk methods from the hotspot table.
+- State how many additional methods exceeded the threshold instead of listing
+  them all.
+- Honor a user-supplied count up to 10. Exceed 10 only when explicitly requested.
+- For five or fewer below-threshold members, name all of them. For larger sets,
+  show the top hotspots and summarize the remaining count and range.
+- Give 1–3 recommendations ordered by expected risk reduction.
+
+## Prioritize
+
+- **HIGH** — both CRAP and coverage exceed their risk thresholds.
+- **MED** — either CRAP or coverage exceeds its threshold.
+- **LOW** — below coverage threshold but complexity is at most 2.
+
+Prefer complex uncovered critical paths (authentication, payment, data access,
+error handling). Deprioritize trivial getters, generated code, migrations, and
+configuration glue.
+
+Do not project a CRAP reduction from an arbitrary target without showing the
+assumption. Recalculate with the stated projected method coverage.
+
+Do not generate tests during analysis. Recommend focused test cases;
+implementation is a separate follow-up.
+
+## Style
+
+- Lead with the risk verdict, not setup narration.
+- Quantify recommendations only from actual line/coverage evidence.
+- Use one compact hotspot table. Do not append the full report template unless
+  the user requested a report.

package/package/corpus/skills/coverage-analysis/references/output-format.md

@@ -0,0 +1,91 @@
+# Output Format
+
+Read and use this template only when the user explicitly requests a full
+markdown coverage report. Normal interpretation, plateau, arithmetic, and
+hotspot requests use the scaled response contract in `SKILL.md` instead.
+
+For an explicit full report, copy the template below **verbatim** for all fixed elements (headings, table headers, emoji, symbols). Only replace `<placeholder>` values with actual data. Do not substitute emoji with text equivalents, do not change `·` to `-`, do not change `×` to `x`, and do not drop section emoji prefixes.
+
+```markdown
+# Coverage Analysis - <ProjectName>
+
+| Metric | Value |
+|--------|-------|
+| **Date** | <YYYY-MM-DD> |
+| **Line Coverage** | <N>% |
+| **Branch Coverage** | <N>% |
+| **Risk Hotspots** | <N> (CRAP > <crap_threshold>) |
+| **Tests** | <N> passed · <N> failed |
+
+## Summary
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| **Line Coverage** | <N>% | <line_threshold>% | ✅ / ❌ |
+| **Branch Coverage** | <N>% | <branch_threshold>% | ✅ / ❌ |
+| **Methods Analyzed** | <N> | — | — |
+| **Risk Hotspots** | <N> | 0 | ✅ / ⚠️ |
+| **Test Result** | <Passed / N tests failed> | — | ✅ / ⚠️ |
+
+> Coverage collected from **<N> of <M> test project(s)**.
+> Outputs saved to: `<coverageDir>/` (markdown summary + raw Cobertura XML).
+> *If HTML/CSV generation ran:* additional reports are at `<coverageDir>/reports/`.
+
+If any coverage provider package was added to test projects, include this note after the summary:
+
+> ℹ️ **Coverage provider package updates**
+> - `coverlet.collector` added to `<K>` project(s): `<TestProject1.csproj>`, `<TestProject2.csproj>`
+> - `Microsoft.Testing.Extensions.CodeCoverage` added to `<M>` project(s): `<TestProject3.csproj>`
+>
+> To revert: `git checkout -- <path-to-each-modified-csproj>`
+
+If all test projects already had a coverage provider, omit this note.
+
+---
+
+## 🔥 Risk Hotspots (Top <N> by CRAP Score)
+
+Methods flagged as high-risk: complex code with low test coverage that is dangerous to change.
+
+| Rank | Method | Class | File | Complexity | Coverage | CRAP Score |
+|------|--------|-------|------|-----------|---------|-----------|
+| 1 | `<method>` | `<class>` | `<file>` | <N> | <N>% | **<score>** |
+| … | … | … | … | … | … | … |
+
+> **CRAP Score** = `Complexity² × (1 − Coverage)³ + Complexity`.
+> Scores above <crap_threshold> are flagged. A score ≤ 5 is considered safe.
+
+---
+
+## 📋 Coverage Gaps by File
+
+Files below the line or branch coverage threshold, ordered by uncovered lines descending:
+
+| File | Line Coverage | Branch Coverage | Uncovered Lines | Priority |
+|------|--------------|----------------|----------------|---------|
+| `<file>` | <N>% | <N>% | <N> | 🔴 HIGH / 🟡 MED / 🟢 LOW |
+| … | … | … | … | … |
+
+---
+
+## 💡 Recommendations
+
+1. **Write tests for the top risk hotspot first** — `<method>` in `<class>` has a CRAP score of <N> (complexity <N>, <N>% coverage). Reducing it to 80% coverage would drop the score to ~<projected>.
+2. **Focus on `<file>`** — <N> uncovered lines, below threshold. <Brief reasoning.>
+3. **<Up to 5 actionable items total, ordered by expected risk reduction.>**
+
+---
+
+## 📁 Reports
+
+| Report | Path |
+|--------|------|
+| Markdown summary (this file) | `<coverageDir>/coverage-analysis.md` |
+| Raw Cobertura XML | `<coberturaXmlPathsUsedForAnalysis>` |
+| HTML (browsable) | `<coverageDir>/reports/index.html` *or* `Not generated (optional — request HTML reports to enable)` |
+| Text summary | `<coverageDir>/reports/Summary.txt` *or* `Not generated` |
+| GitHub markdown | `<coverageDir>/reports/SummaryGithub.md` *or* `Not generated` |
+| CSV data | `<coverageDir>/reports/Summary.csv` *or* `Not generated` |
+```
+
+If ReportGenerator has not run, mark the HTML/Text/GitHub-markdown/CSV rows as `Not generated (optional — request HTML reports to enable)`. Do not invent paths for files that have not been produced. For **Raw Cobertura XML**, list the actual XML file path(s) used in analysis (for from-scratch runs this is typically under `<coverageDir>/raw/`; for existing-data runs this may be under `TestResults/` or another user-supplied location).

package/package/corpus/skills/coverage-analysis/references/report-generation.md

@@ -0,0 +1,58 @@
+# Coverage Analysis — ReportGenerator HTML/CSV reports
+
+Read this file **only** when the user explicitly asked for HTML/CSV reports and
+the direct coverage/risk answer has already been delivered.
+
+## Verify or install ReportGenerator
+
+```powershell
+$rgAvailable = $false
+$rgCommand = Get-Command reportgenerator -ErrorAction SilentlyContinue
+if ($rgCommand) {
+    $rgAvailable = $true
+    Write-Host "RG_INSTALLED:already-present"
+} else {
+    $rgToolPath = Join-Path "<COVERAGE_DIR>" ".tools"
+# Cratis: Downloads or installs a tool: requires the user's approval; prefer a pinned version (`dotnet tool install <tool> --version <x>`)
+    dotnet tool install dotnet-reportgenerator-globaltool --tool-path $rgToolPath
+    if ($LASTEXITCODE -eq 0) {
+        $env:PATH = "$rgToolPath$([System.IO.Path]::PathSeparator)$env:PATH"
+        $rgCommand = Get-Command reportgenerator -ErrorAction SilentlyContinue
+        if ($rgCommand) {
+            $rgAvailable = $true
+            Write-Host "RG_INSTALLED:true (tool-path: $rgToolPath)"
+        } else {
+            Write-Host "RG_INSTALLED:false"
+            Write-Host "RG_INSTALL_ERROR:reportgenerator-not-available"
+        }
+    } else {
+        Write-Host "RG_INSTALLED:false"
+        Write-Host "RG_INSTALL_ERROR:reportgenerator-not-available"
+    }
+}
+Write-Host "RG_AVAILABLE:$rgAvailable"
+```
+
+If installation fails (no internet), keep `RG_AVAILABLE:false`, leave the existing user-facing summary as the final output, and note that HTML reports were skipped.
+
+## Step 7: Generate HTML/CSV reports
+
+```powershell
+$reportsDir = Join-Path "<COVERAGE_DIR>" "reports"
+if ($rgAvailable) {
+    reportgenerator `
+        -reports:"<semicolon-separated COBERTURA paths>" `
+        -targetdir:$reportsDir `
+        -reporttypes:"Html;TextSummary;MarkdownSummaryGithub;CsvSummary" `
+        -title:"Coverage Report" `
+        -tag:"coverage-analysis-skill"
+
+    Get-Content (Join-Path $reportsDir "Summary.txt") -ErrorAction SilentlyContinue
+} else {
+    Write-Host "REPORTGENERATOR_SKIPPED:true"
+}
+```
+
+After report generation completes successfully, you may follow up with a short
+message pointing the user to the generated HTML report (one paragraph, no need
+to repeat the summary).

package/package/corpus/skills/coverage-analysis/references/setup-discovery.md

@@ -0,0 +1,307 @@
+# Coverage Analysis — setup and discovery
+
+## Contents
+
+- Step 1: Locate the solution or project
+- Step 2: Create the output directory
+- Step 2b: Discover or accept existing Cobertura XML (required for the existing-data path)
+- Step 2c: Recommend ignoring `TestResults/`
+
+Read this file only when the user did not supply usable coverage evidence and
+the request requires workspace discovery or fresh collection. Do not read or run
+these probes for a supplied excerpt or valid Cobertura path.
+
+## Step 1: Locate the solution or project
+
+Given the user's path (default: current directory), find the entry point.
+If the user or the repository's documented coverage command selects a specific
+`.sln`, `.slnx`, `.slnf`, or `.csproj`, pass that exact file as `$root`; do not
+replace it with a discovered alternative. Directory discovery stops on multiple
+solutions or, when no solution exists, multiple projects. Request an explicit
+entry point rather than selecting the first.
+
+```powershell
+$root = "<user-or-repository-selected-file-or-directory>"
+$requested = Get-Item -LiteralPath $root -ErrorAction Stop
+$entry = $null
+if (-not $requested.PSIsContainer) {
+    if ($requested.Extension -notin @('.sln', '.slnx', '.slnf', '.csproj')) {
+        throw "Unsupported entry point: $($requested.FullName)"
+    }
+    $entry = $requested
+    $root = $requested.DirectoryName
+} else {
+    $root = $requested.FullName
+    $candidates = @(Get-ChildItem -LiteralPath $root -File -Recurse -Depth 2 -ErrorAction Stop |
+        Where-Object { $_.Extension -in @('.sln', '.slnx') -and $_.FullName -notmatch '[/\\](obj|bin)[/\\]' })
+    if ($candidates.Count -eq 0) {
+        $candidates = @(Get-ChildItem -LiteralPath $root -Filter "*.csproj" -File -Recurse -Depth 2 -ErrorAction Stop |
+            Where-Object { $_.FullName -notmatch '[/\\](obj|bin)[/\\]' })
+    }
+    if ($candidates.Count -gt 1) {
+        throw "Ambiguous entry point under $root. Specify one .sln, .slnx, .slnf, or .csproj: $($candidates.FullName -join ', ')"
+    }
+    if ($candidates.Count -eq 1) { $entry = $candidates[0] }
+}
+if ($entry) {
+    $entryType = if ($entry.Extension -eq '.csproj') { 'Project' } else { 'Solution' }
+    Write-Host "ENTRY_TYPE:$entryType"; Write-Host "ENTRY:$($entry.FullName)"
+} else {
+    Write-Host "ENTRY_TYPE:NotFound"
+}
+
+# Test projects: search the requested directory, then its containing Git root only.
+$searchRoots = @($root)
+$gitOutput = @(git -C $root rev-parse --show-toplevel 2>&1)
+if ($LASTEXITCODE -eq 0) {
+    $gitRoot = [string]$gitOutput[0]
+} else {
+    $gitError = $gitOutput | Out-String
+    if ($gitError -notmatch 'not a git repository \(or any of the parent directories\): \.git') {
+        throw "Git root lookup failed: $gitError"
+    }
+    $gitRoot = $null
+}
+if ($gitRoot) { $gitRoot = [System.IO.Path]::GetFullPath($gitRoot) }
+if ($gitRoot -and $gitRoot -ne $root) {
+    $sep = [System.IO.Path]::DirectorySeparatorChar
+    $prefix = $gitRoot.TrimEnd($sep) + $sep
+    if (-not $root.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+        throw "Git root is not a containing directory: $gitRoot"
+    }
+    $searchRoots += $gitRoot
+}
+
+function Get-SolutionProjects($solution) {
+    $text = Get-Content -LiteralPath $solution.FullName -Raw -ErrorAction Stop
+    if ($solution.Extension -eq '.slnx') {
+        $xml = [xml]$text
+        if ($xml.DocumentElement.Name -ne 'Solution') { throw "Invalid solution: $($solution.FullName)" }
+        $paths = @($xml.SelectNodes('//Project[@Path]') | ForEach-Object { $_.Path })
+    } elseif ($solution.Extension -eq '.sln') {
+        if ($text -notmatch 'Microsoft Visual Studio Solution File, Format Version') {
+            throw "Invalid solution: $($solution.FullName)"
+        }
+        $paths = @([regex]::Matches($text, '(?m)^Project\("[^"]+"\)\s*=\s*"[^"]*",\s*"([^"]+)",') |
+            ForEach-Object { $_.Groups[1].Value } |
+            Where-Object { [System.IO.Path]::GetExtension($_) -eq '.csproj' })
+    } else {
+        throw "Unsupported underlying solution: $($solution.FullName)"
+    }
+    foreach ($path in $paths) {
+        if ([System.IO.Path]::GetExtension($path) -eq '.csproj') {
+            $relative = $path.Replace('\', [System.IO.Path]::DirectorySeparatorChar)
+            [System.IO.Path]::GetFullPath((Join-Path $solution.DirectoryName $relative))
+        }
+    }
+}
+
+# Scope before reading/classifying projects: solution membership, filter membership,
+# or the single project that the selected test command actually targets.
+if ($entry) {
+    if ($entry.Extension -eq '.csproj') {
+        $projectPaths = @($entry.FullName)
+    } elseif ($entry.Extension -eq '.slnf') {
+        $filter = Get-Content -LiteralPath $entry.FullName -Raw -ErrorAction Stop | ConvertFrom-Json -ErrorAction Stop
+        if (-not $filter.solution.path -or $null -eq $filter.solution.projects) {
+            throw "Invalid solution filter: $($entry.FullName)"
+        }
+        $solutionPath = $filter.solution.path.Replace('\', [System.IO.Path]::DirectorySeparatorChar)
+        $solution = Get-Item -LiteralPath (Join-Path $entry.DirectoryName $solutionPath) -ErrorAction Stop
+        $members = @(Get-SolutionProjects $solution)
+        $projectPaths = @($filter.solution.projects | ForEach-Object {
+            $relative = $_.Replace('\', [System.IO.Path]::DirectorySeparatorChar)
+            $project = Get-Item -LiteralPath (Join-Path $solution.DirectoryName $relative) -ErrorAction Stop
+            if ($members -notcontains $project.FullName) { throw "Filtered project is not in the solution: $($project.FullName)" }
+            $project.FullName
+        })
+    } else {
+        $projectPaths = @(Get-SolutionProjects $entry)
+    }
+    $projects = @($projectPaths | Select-Object -Unique | ForEach-Object {
+        Get-Item -LiteralPath $_ -ErrorAction Stop
+    })
+    $testProjects = @($projects | Where-Object {
+        (Select-String -LiteralPath $_.FullName -Pattern 'Microsoft\.NET\.Test\.Sdk|xunit|nunit|MSTest\.TestAdapter|"MSTest"|MSTest\.TestFramework|TUnit' -Quiet -ErrorAction Stop) -or
+        $_.Name -match '(?i)(test|spec)'
+    })
+} else {
+    $testProjects = @()
+    foreach ($sr in $searchRoots) {
+        $projects = @(Get-ChildItem -LiteralPath $sr -Filter "*.csproj" -File -Recurse -Depth 5 -ErrorAction Stop |
+            Where-Object { $_.FullName -notmatch '[/\\](obj|bin)[/\\]' })
+        $testProjects = @($projects | Where-Object {
+            Select-String -LiteralPath $_.FullName -Pattern 'Microsoft\.NET\.Test\.Sdk|xunit|nunit|MSTest\.TestAdapter|"MSTest"|MSTest\.TestFramework|TUnit' -Quiet -ErrorAction Stop
+        })
+        if ($testProjects.Count -eq 0) {
+            $testProjects = @($projects | Where-Object { $_.Name -match '(?i)(test|spec)' })
+        }
+        if ($testProjects.Count -gt 0) {
+            if ($sr -ne $root) { Write-Host "SEARCHED:$sr" }
+            break
+        }
+    }
+}
+Write-Host "TEST_PROJECTS:$($testProjects.Count)"
+$testProjects | ForEach-Object { Write-Host "TEST_PROJECT:$($_.FullName)" }
+
+# Project-system classification controls whether the automatic dotnet/provider path is safe.
+$classicTestProjects = @($testProjects | Where-Object {
+    $text = Get-Content -LiteralPath $_.FullName -Raw -ErrorAction Stop
+    $hasSdk = $text -match '<Project[^>]+\bSdk\s*=' -or $text -match '<Sdk\b'
+    $hasPackagesConfig = Test-Path (Join-Path $_.DirectoryName "packages.config")
+    $hasClassicSignals = $text -match '\bToolsVersion\s*=' -or
+        $text -match 'Microsoft\.(Common\.props|CSharp\.targets)' -or
+        $text -match '<Compile\s+Include='
+    $hasPackagesConfig -or (-not $hasSdk -and $hasClassicSignals)
+})
+Write-Host "CLASSIC_TEST_PROJECTS:$($classicTestProjects.Count)"
+$classicTestProjects | ForEach-Object { Write-Host "CLASSIC_TEST_PROJECT:$($_.FullName)" }
+$sdkTestProjects = @($testProjects | Where-Object {
+    $classicTestProjects.FullName -notcontains $_.FullName
+})
+Write-Host "SDK_TEST_PROJECTS:$($sdkTestProjects.Count)"
+$sdkTestProjects | ForEach-Object { Write-Host "SDK_TEST_PROJECT:$($_.FullName)" }
+
+# Resolve the test output root (where coverage-analysis artifacts will be written)
+if ($testProjects.Count -eq 0) {
+    if ($gitRoot) {
+        $testOutputRoot = $gitRoot
+    } else {
+        $testOutputRoot = $root
+    }
+} elseif ($testProjects.Count -eq 1) {
+    $testOutputRoot = $testProjects[0].DirectoryName
+} else {
+    # Multiple test projects — find their deepest common parent directory
+    $dirs = $testProjects | ForEach-Object { $_.DirectoryName }
+    $common = $dirs[0]
+    foreach ($d in $dirs[1..($dirs.Count-1)]) {
+        $sep = [System.IO.Path]::DirectorySeparatorChar
+        while (-not $d.StartsWith("$common$sep", [System.StringComparison]::OrdinalIgnoreCase) -and $d -ne $common) {
+            $prevCommon = $common
+            $common = Split-Path $common -Parent
+            # Terminate if we can no longer move up (at filesystem root or no parent)
+            if ([string]::IsNullOrEmpty($common) -or $common -eq $prevCommon) {
+                $common = $null
+                break
+            }
+        }
+    }
+    if ([string]::IsNullOrEmpty($common)) {
+        # Fallback when no common parent directory exists (e.g., projects on different drives)
+        if ($gitRoot) {
+            $testOutputRoot = $gitRoot
+        } else {
+            $testOutputRoot = $root
+        }
+    } else {
+        $testOutputRoot = $common
+    }
+}
+Write-Host "TEST_OUTPUT_ROOT:$testOutputRoot"
+```
+
+- If `ENTRY_TYPE:NotFound` and SDK-style test projects were found → use the test projects directly as `dotnet test` entry points.
+- If `ENTRY_TYPE:NotFound` and classic test projects were found → use only the repository's documented coverage command; do not infer `dotnet test`.
+- If `ENTRY_TYPE:NotFound` and no test projects found → stop: `No .sln, .slnx, or test projects found under <path>. Provide the path to your .NET solution, filter, or project.`
+- A missing/unreadable requested path, failed lookup, or ambiguous entry point is a discovery blocker, not measured zero coverage or evidence of an empty suite. Do not continue collection after a discovery error.
+- Discovery is an inventory, not permission to expand collection scope. Pass the
+  exact selected entry point to `run-tests` and collect only its requested
+  project graph. Do not replace a selected `.csproj` or `.slnf` with every test
+  project found under the containing Git root. Apply the classic-project safety
+  rules below within that selected graph.
+- Selected-entry arrays contain only the projects targeted by that entry:
+  solution members, filter members, or one explicit project. Transitive build
+  dependencies are not additional test-run targets. For a generated or
+  nonstandard entry graph that these formats cannot represent, stop and use
+  the repository's evaluated target inventory rather than scanning siblings.
+- If `TEST_PROJECTS:0` and `EXISTING_COBERTURA_COUNT` > 0 (Step 2b) → continue with existing Cobertura XML analysis (no `dotnet test` run).
+- If `TEST_PROJECTS:0` and `EXISTING_COBERTURA_COUNT` == 0 → stop: `No test projects found (expected projects with 'Test' or 'Spec' in the name), and no existing Cobertura XML was provided. Add a test project or provide a Cobertura file path.`
+- If `CLASSIC_TEST_PROJECTS` is nonzero and no existing Cobertura XML is found,
+  search scripts/CI/docs for a repository-owned coverage command. Use it if it
+  emits Cobertura.
+- If classic projects are the only test projects and no repository command
+  exists, stop: `Classic non-SDK or packages.config test project detected. The
+  automatic SDK-style coverage-provider path would modify this project
+  incorrectly. Run the repository's supported coverage workflow and provide its
+  Cobertura XML.`
+  This is a hard stop: do not create or run a temporary SDK project against the
+  classic source, because its coverage would belong to the substitute assembly,
+  not the requested test project.
+- In a mixed solution, run automatic collection only for `SDK_TEST_PROJECTS`.
+  Never run the solution entry point if it would include classic projects.
+  Clearly label the result partial until repository-owned Cobertura data for the
+  classic projects is also available.
+
+## Step 2: Create the output directory
+
+```powershell
+$coverageDir = Join-Path $testOutputRoot "TestResults" "coverage-analysis"
+if (Test-Path $coverageDir) { Remove-Item $coverageDir -Recurse -Force }
+New-Item -ItemType Directory -Path $coverageDir -Force | Out-Null
+Write-Host "COVERAGE_DIR:$coverageDir"
+```
+
+This step only manages the `TestResults/coverage-analysis/` subdirectory (skill-owned outputs). It must never delete user-supplied Cobertura files — those live one level up at `TestResults/coverage.cobertura.xml` (or wherever the user pointed). If the user provided a path that *is* `TestResults/coverage-analysis/...`, copy the file aside before this step recreates the directory.
+
+## Step 2b: Discover or accept existing Cobertura XML (required for the existing-data path)
+
+If the user supplied a Cobertura XML path explicitly, use it. Otherwise probe well-known locations and any path the user mentioned:
+
+```powershell
+# 1. Honor a user-supplied path first (highest priority)
+$coberturaFiles = @()
+if ($userSuppliedCoberturaPath) {
+    $coberturaFiles = @(Get-Item -LiteralPath $userSuppliedCoberturaPath -ErrorAction Stop)
+}
+
+# 2. Otherwise scan TestResults/ at the repo/test root for any *.cobertura.xml
+if ($coberturaFiles.Count -eq 0) {
+    $searchPaths = @(
+        (Join-Path $testOutputRoot "TestResults"),
+        (Join-Path $root "TestResults")
+    ) | Where-Object { $_ -and (Test-Path $_) } | Select-Object -Unique
+    foreach ($sp in $searchPaths) {
+        $found = @(Get-ChildItem -LiteralPath $sp -Filter "*.cobertura.xml" -Recurse -ErrorAction Stop |
+            Where-Object { $_.FullName -notmatch '[/\\]coverage-analysis[/\\]raw[/\\]' })
+        if ($found.Count -gt 0) { $coberturaFiles = $found; break }
+    }
+}
+
+Write-Host "EXISTING_COBERTURA_COUNT:$($coberturaFiles.Count)"
+$coberturaFiles | ForEach-Object { Write-Host "EXISTING_COBERTURA:$($_.FullName)" }
+```
+
+- If `EXISTING_COBERTURA_COUNT` > 0 → skip fresh collection and analyze these paths.
+- If `EXISTING_COBERTURA_COUNT` == 0 and all test projects are SDK-style →
+  invoke `run-tests` to select the repository-compatible platform/provider
+  command and collect Cobertura.
+- If `EXISTING_COBERTURA_COUNT` == 0 and only classic/packages.config projects
+  exist → use a repository-owned coverage command that emits Cobertura;
+  otherwise stop with the message above.
+- If `EXISTING_COBERTURA_COUNT` == 0 and both classic and SDK-style projects
+  exist → ask `run-tests` to collect only for `SDK_TEST_PROJECTS` and mark the
+  result partial until classic-project Cobertura is available.
+
+## Step 2c: Recommend ignoring `TestResults/`
+
+```powershell
+$pattern = "**/TestResults/"
+$gitRoot = (git -C $testOutputRoot rev-parse --show-toplevel 2>$null)
+if ($gitRoot) { $gitRoot = [System.IO.Path]::GetFullPath($gitRoot) }
+if ($gitRoot) {
+    $gitignorePath = Join-Path $gitRoot ".gitignore"
+    $alreadyIgnored = $false
+    if (Test-Path $gitignorePath) {
+        $alreadyIgnored = (Select-String -Path $gitignorePath -Pattern '^\s*(\*\*/)?TestResults/?\s*$' -Quiet)
+    }
+    if ($alreadyIgnored) {
+        Write-Host "GITIGNORE_RECOMMENDATION:already-present"
+    } else {
+        Write-Host "GITIGNORE_RECOMMENDATION:$pattern"
+    }
+} else {
+    Write-Host "GITIGNORE_RECOMMENDATION:$pattern"
+}
+```

package/package/corpus/skills/coverage-analysis/scripts/Compute-CrapScores.ps1

@@ -0,0 +1,80 @@
+<#
+.SYNOPSIS
+Compute CRAP = complexity^2 * (1 - line coverage)^3 + complexity.
+.DESCRIPTION
+Missing complexity or executable lines yield unknown, never complexity=1/coverage=0.
+Legacy output retains OVERALL_*, TOTAL_METHODS, FLAGGED_METHODS and HOTSPOTS markers
+only when all requested measurements are representable. -OutputFormat json-v1
+emits one provenance-bearing JSON document. Diagnostics go to stderr.
+Thresholds and hotspot ordering use raw scores; only displayed scores are rounded.
+Exit codes: 0 complete, 2 invalid input, 3 incomplete/unrepresentable evidence.
+#>
+param(
+    [Parameter(Mandatory)][string[]]$CoberturaPath,
+    [ValidateRange(0,[int]::MaxValue)][int]$CrapThreshold = 30,
+    [ValidateRange(1,[int]::MaxValue)][int]$TopN = 10,
+    [ValidateSet('legacy', 'json-v1')][string]$OutputFormat = 'legacy'
+)
+
+try {
+    . "$PSScriptRoot\CoverageData.ps1"
+} catch {
+    $diagnostic = @{ code = 'DEPENDENCY_UNAVAILABLE'; severity = 'error'; message = $_.Exception.Message; path = "$PSScriptRoot\CoverageData.ps1" }
+    [Console]::Error.WriteLine("$($diagnostic.code): $($diagnostic.message)")
+    if ($OutputFormat -eq 'json-v1') {
+        @{
+            schema_version = '1'; tool = 'Compute-CrapScores'; tool_version = '1.0'; status = 'error'
+            scope = @{}; inputs = @(); diagnostics = @($diagnostic); data = @{}
+        } | ConvertTo-Json -Depth 5
+    }
+    exit 2
+}
+$scope = @{ identity = 'reported-module-file-class-signature'; source_revision = $null; top = $TopN; crap_threshold = $CrapThreshold }
+try {
+    $coverage = Get-CoverageData $CoberturaPath
+} catch {
+    $diagnostics = @([pscustomobject]@{ code = 'INVALID_INPUT'; severity = 'error'; message = $_.Exception.Message })
+    Write-CoverageDiagnostics $diagnostics
+    if ($OutputFormat -eq 'json-v1') { Write-CoverageJson 'Compute-CrapScores' 'error' $scope @() $diagnostics @{} }
+    exit 2
+}
+foreach ($method in $coverage.Methods) {
+    $score = if ($null -ne $method.Complexity -and $method.LineCoverageStatus -eq 'exact') {
+        [math]::Pow($method.Complexity, 2) * [math]::Pow(1 - $method.CoveredLines / [double]$method.TotalLines, 3) + $method.Complexity
+    } else { $null }
+    $method | Add-Member -NotePropertyName CrapScore -NotePropertyValue $score
+}
+$ranked = @($coverage.Methods | Where-Object { $null -ne $_.CrapScore } |
+    Sort-Object -Property @{Expression='CrapScore';Descending=$true}, Class, Method, File, Signature)
+$hotspots = @($ranked | Select-Object -First $TopN)
+$unknown = @($coverage.Methods | Where-Object { $null -eq $_.CrapScore }).Count
+$coverage.Summary.flagged_methods = @($ranked | Where-Object { $_.CrapScore -gt $CrapThreshold }).Count
+$coverage.Summary.unknown_crap_methods = $unknown
+foreach ($method in $ranked) {
+    $method.CrapScore = [math]::Round($method.CrapScore, 2)
+}
+foreach ($metric in @('line', 'branch')) {
+    if ($coverage.Summary["overall_${metric}_coverage_status"] -in @('unknown', 'bounded')) {
+        Add-CoverageDiagnostic $coverage.Diagnostics 'AGGREGATE_UNKNOWN' "Overall $metric coverage cannot be derived from overlapping report counters." ''
+    }
+}
+$partial = -not $coverage.Methods.Count -or $unknown -gt 0 -or
+    $coverage.Summary.overall_line_coverage_status -in @('unknown', 'bounded') -or
+    $coverage.Summary.overall_branch_coverage_status -in @('unknown', 'bounded')
+Write-CoverageDiagnostics $coverage.Diagnostics
+if ($OutputFormat -eq 'json-v1') {
+    Write-CoverageJson 'Compute-CrapScores' $(if ($partial) { 'partial' } else { 'complete' }) $scope $coverage.Inputs $coverage.Diagnostics @{
+        methods = $coverage.Methods; hotspots = $hotspots; summary = $coverage.Summary
+    }
+} elseif (-not $partial) {
+    $line = if ($coverage.Summary.overall_line_coverage_status -eq 'not-applicable') { 0 } else { $coverage.Summary.overall_line_coverage }
+    $branch = if ($coverage.Summary.overall_branch_coverage_status -eq 'not-applicable') { 0 } else { $coverage.Summary.overall_branch_coverage }
+    Write-Output "OVERALL_LINE_COVERAGE:$line"
+    Write-Output "OVERALL_BRANCH_COVERAGE:$branch"
+    Write-Output "TOTAL_METHODS:$($coverage.Methods.Count)"
+    Write-Output "FLAGGED_METHODS:$($coverage.Summary.flagged_methods)"
+    $legacy = @($hotspots | Select-Object Class, Method, Signature, File, TotalLines, CoveredLines, LineCoverage, Complexity, CrapScore)
+    Write-Output "HOTSPOTS:$(ConvertTo-Json -InputObject $legacy -Compress)"
+}
+if ($partial) { exit 3 }
+exit 0