@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/coverage-analysis/scripts/CoverageData.ps1

@@ -0,0 +1,272 @@
+# Shared, report-identity-scoped Cobertura normalization. This does not attest
+# that a report was collected from the current checkout.
+
+function New-CoverageMap {
+    return [System.Collections.Generic.Dictionary[string, object]]::new([StringComparer]::Ordinal)
+}
+
+function Add-CoverageDiagnostic($Diagnostics, [string]$Code, [string]$Message, [string]$Path) {
+    $Diagnostics.Add([pscustomobject]@{ code = $Code; severity = 'warning'; message = $Message; path = $Path })
+}
+
+function Read-CoverageInteger([string]$Text, [string]$Name, [long]$Minimum = 0) {
+    $value = 0L
+    if (-not [long]::TryParse($Text, [Globalization.NumberStyles]::Integer,
+            [Globalization.CultureInfo]::InvariantCulture, [ref]$value) -or $value -lt $Minimum) {
+        throw [FormatException]::new("Invalid $Name value '$Text'.")
+    }
+    return $value
+}
+
+function Add-CoverageLine($Map, $Node, [string]$Key, [string]$ReportId) {
+    $number = Read-CoverageInteger $Node.GetAttribute('number') 'line number' 1
+    $hits = Read-CoverageInteger $Node.GetAttribute('hits') 'line hits'
+    $lineKey = "$Key`n$number"
+    if (-not $Map.ContainsKey($lineKey)) {
+        $Map[$lineKey] = @{
+            Covered = $false
+            NonBranch = $false
+            ConflictingBranches = $false
+            Branches = [System.Collections.Generic.List[object]]::new()
+            Observations = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
+        }
+    }
+    $entry = $Map[$lineKey]
+    $entry.Covered = $entry.Covered -or $hits -gt 0
+    if (-not $entry.Observations.Add($ReportId)) { return }
+    $branch = $Node.GetAttribute('branch')
+    if ($branch -and $branch -notin @('true', 'false')) {
+        throw [FormatException]::new("Invalid branch flag '$branch'.")
+    }
+    if ($branch -ne 'true') {
+        $entry.NonBranch = $true
+        if ($entry.Branches.Count) { $entry.ConflictingBranches = $true }
+        return
+    }
+    if ($entry.NonBranch) { $entry.ConflictingBranches = $true }
+    $raw = $Node.GetAttribute('condition-coverage')
+    if ($raw -notmatch '^\s*[\d.]+%\s*\((\d+)/(\d+)\)\s*$') {
+        $entry.Branches.Add(@{ Total = $null; Covered = $null; Conditions = $null })
+        return
+    }
+    $covered = Read-CoverageInteger $Matches[1] 'covered branches'
+    $total = Read-CoverageInteger $Matches[2] 'total branches' 1
+    if ($covered -gt $total) { throw [FormatException]::new('Covered branches exceed total branches.') }
+
+    # Cobertura jump conditions describe two outcomes, not which outcome a
+    # 50% observation took. Keep that ambiguity even when condition ids match.
+    $conditions = New-CoverageMap
+    $nodes = @($Node.SelectNodes('conditions/condition'))
+    $conditionSum = 0
+    $usable = $nodes.Count -gt 0 -and $total -eq 2 * $nodes.Count
+    foreach ($condition in $nodes) {
+        $id = $condition.GetAttribute('number')
+        $coverage = $condition.GetAttribute('coverage')
+        if ($condition.GetAttribute('type') -ne 'jump' -or -not $id -or
+            $conditions.ContainsKey($id) -or $coverage -notmatch '^(0|50|100)(?:\.0+)?%$') {
+            $usable = $false
+            continue
+        }
+        $count = [int]$Matches[1] / 50
+        $conditions[$id] = $count
+        $conditionSum += $count
+    }
+    if (-not $usable -or $conditionSum -ne $covered) { $conditions = $null }
+    $entry.Branches.Add(@{ Total = $total; Covered = $covered; Conditions = $conditions })
+}
+
+function Get-CoverageMeasure($Lines) {
+    $coveredLines = @($Lines.Values | Where-Object Covered).Count
+    $linePercent = if ($Lines.Count) { [math]::Round(100.0 * $coveredLines / $Lines.Count, 1) } else { $null }
+    $lower = 0L
+    $upper = 0L
+    $total = 0L
+    $unknown = $Lines.Count -eq 0
+    foreach ($line in $Lines.Values) {
+        $observations = @($line.Branches)
+        if (-not $observations.Count) { continue }
+        if ($line.ConflictingBranches -or @($observations | Where-Object { $null -eq $_.Total }).Count) {
+            $unknown = $true
+            continue
+        }
+        $totals = @($observations | ForEach-Object { $_.Total } | Sort-Object -Unique)
+        if ($totals.Count -ne 1 -or $null -eq $totals[0]) { $unknown = $true; continue }
+        $capacity = $totals[0]
+        $total += $capacity
+        $useConditions = $true
+        $conditionIds = $null
+        foreach ($observation in $observations) {
+            if ($null -eq $observation.Conditions) { $useConditions = $false; break }
+            $ids = @($observation.Conditions.Keys | Sort-Object -CaseSensitive)
+            $identity = ConvertTo-Json -InputObject $ids -Compress
+            if ($null -ne $conditionIds -and $conditionIds -cne $identity) { $useConditions = $false; break }
+            $conditionIds = $identity
+        }
+        if ($useConditions) {
+            foreach ($id in $observations[0].Conditions.Keys) {
+                $counts = @($observations | ForEach-Object { $_.Conditions[$id] })
+                $lower += ($counts | Measure-Object -Maximum).Maximum
+                $upper += [math]::Min(2, ($counts | Measure-Object -Sum).Sum)
+            }
+        } else {
+            $counts = @($observations | ForEach-Object { $_.Covered })
+            $lower += ($counts | Measure-Object -Maximum).Maximum
+            $upper += [math]::Min($capacity, ($counts | Measure-Object -Sum).Sum)
+        }
+    }
+    $branchStatus = if ($unknown) { 'unknown' } elseif (-not $total) { 'not-applicable' } elseif ($lower -eq $upper) { 'exact' } else { 'bounded' }
+    return [pscustomobject]@{
+        TotalLines = $Lines.Count
+        CoveredLines = $coveredLines
+        LineCoverage = $linePercent
+        LineCoverageStatus = $(if ($Lines.Count) { 'exact' } else { 'unknown' })
+        TotalBranches = $(if ($unknown) { $null } else { $total })
+        CoveredBranches = $(if ($branchStatus -in @('exact', 'not-applicable')) { [long]$lower } else { $null })
+        BranchCoverage = $(if ($branchStatus -eq 'exact') { [math]::Round(100.0 * $lower / $total, 1) } else { $null })
+        BranchCoverageStatus = $branchStatus
+        CoveredBranchesLower = $(if (-not $unknown) { [long]$lower } else { $null })
+        CoveredBranchesUpper = $(if (-not $unknown) { [long]$upper } else { $null })
+        BranchCoverageLower = $(if (-not $unknown -and $total) { [math]::Round(100.0 * $lower / $total, 1) } else { $null })
+        BranchCoverageUpper = $(if (-not $unknown -and $total) { [math]::Round(100.0 * $upper / $total, 1) } else { $null })
+    }
+}
+
+function Get-CoverageData([string[]]$Paths) {
+    if (-not $Paths.Count) { throw [ArgumentException]::new('At least one Cobertura report is required.') }
+    $methods = New-CoverageMap
+    $classLines = New-CoverageMap
+    $methodLines = New-CoverageMap
+    $inputs = [System.Collections.Generic.List[object]]::new()
+    $reports = [System.Collections.Generic.List[object]]::new()
+    $diagnostics = [System.Collections.Generic.List[object]]::new()
+    $seen = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
+    $allClassesHaveLines = $true
+    foreach ($path in ($Paths | Sort-Object -Unique -CaseSensitive)) {
+        $resolved = (Get-Item -LiteralPath $path -ErrorAction Stop).FullName
+        $bytes = [IO.File]::ReadAllBytes($resolved)
+        $hash = [Convert]::ToHexString([Security.Cryptography.SHA256]::HashData($bytes)).ToLowerInvariant()
+        $inputs.Add([pscustomobject]@{ path = $resolved; sha256 = $hash })
+        if (-not $seen.Add($hash)) { continue }
+        $xml = [xml]::new()
+        $xml.XmlResolver = $null
+        $stream = [IO.MemoryStream]::new($bytes, $false)
+        try { $xml.Load($stream) } finally { $stream.Dispose() }
+        if ($xml.DocumentElement.Name -ne 'coverage') { throw [FormatException]::new("Not a Cobertura report: $path") }
+        $coverageRoot = $xml.DocumentElement
+        $report = @{ line = $null; branch = $null }
+        foreach ($metric in @('line', 'branch')) {
+            $prefix = if ($metric -eq 'line') { 'lines' } else { 'branches' }
+            $valid = $coverageRoot.GetAttribute("$prefix-valid")
+            $covered = $coverageRoot.GetAttribute("$prefix-covered")
+            if ($valid -or $covered) {
+                $denominator = Read-CoverageInteger $valid "$prefix-valid"
+                $numerator = Read-CoverageInteger $covered "$prefix-covered"
+                if ($numerator -gt $denominator) { throw [FormatException]::new("$prefix-covered exceeds $prefix-valid.") }
+                $report[$metric] = @{ Total = $denominator; Covered = $numerator }
+            }
+        }
+        $reports.Add($report)
+        $reportMethods = [System.Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)
+        foreach ($class in $xml.SelectNodes('/coverage/packages/package/classes/class')) {
+            $filename = $class.GetAttribute('filename').Replace('\', '/')
+            $className = $class.GetAttribute('name')
+            $module = $class.ParentNode.ParentNode.GetAttribute('name')
+            if (-not $filename -or -not $className) { throw [FormatException]::new('Class name and filename are required.') }
+            $sourceKey = ConvertTo-Json -InputObject @($module, $filename) -Compress
+            $classNodes = @($class.SelectNodes('lines/line'))
+            if (-not $classNodes.Count) { $allClassesHaveLines = $false }
+            foreach ($line in $classNodes) { Add-CoverageLine $classLines $line $sourceKey $hash }
+            foreach ($method in $class.SelectNodes('methods/method')) {
+                $name = $method.GetAttribute('name')
+                if (-not $name) { throw [FormatException]::new('Method name is required.') }
+                $signature = $method.GetAttribute('signature')
+                $key = ConvertTo-Json -InputObject @($module, $filename, $className, $name, $signature) -Compress
+                if (-not $reportMethods.Add($key)) {
+                    throw [FormatException]::new("Duplicate method identity for $className.$name; signatures or source mapping are ambiguous.")
+                }
+                if (-not $methods.ContainsKey($key)) {
+                    $methods[$key] = @{
+                        Module = $module; Class = $className; Method = $name; Signature = $signature; File = $filename
+                        Lines = (New-CoverageMap)
+                        Complexities = [System.Collections.Generic.HashSet[long]]::new()
+                    }
+                }
+                $entry = $methods[$key]
+                $complexity = $method.GetAttribute('complexity')
+                if ($complexity) { [void]$entry.Complexities.Add((Read-CoverageInteger $complexity 'complexity' 1)) }
+                foreach ($line in $method.SelectNodes('lines/line')) {
+                    Add-CoverageLine $entry.Lines $line '' $hash
+                    Add-CoverageLine $methodLines $line $sourceKey $hash
+                }
+            }
+        }
+    }
+    $result = [System.Collections.Generic.List[object]]::new()
+    foreach ($entry in $methods.Values) {
+        $measure = Get-CoverageMeasure $entry.Lines
+        $complexity = if ($entry.Complexities.Count -eq 1) { @($entry.Complexities)[0] } else { $null }
+        $item = [ordered]@{
+            Class = $entry.Class; Method = $entry.Method; Signature = $entry.Signature; File = $entry.File
+            Module = $entry.Module; Complexity = $complexity
+            ComplexityStatus = $(if ($null -ne $complexity) { 'exact' } else { 'unknown' })
+        }
+        foreach ($property in $measure.PSObject.Properties) { $item[$property.Name] = $property.Value }
+        $item.UncoveredLines = $measure.TotalLines - $measure.CoveredLines
+        if ($null -eq $complexity) {
+            Add-CoverageDiagnostic $diagnostics 'COMPLEXITY_UNKNOWN' "Missing or conflicting complexity for $($entry.Class).$($entry.Method)." $entry.File
+        }
+        if ($measure.LineCoverageStatus -eq 'unknown') {
+            Add-CoverageDiagnostic $diagnostics 'METHOD_LINES_UNKNOWN' "No executable-line evidence for $($entry.Class).$($entry.Method)." $entry.File
+        }
+        if ($measure.BranchCoverageStatus -in @('unknown', 'bounded')) {
+            Add-CoverageDiagnostic $diagnostics 'BRANCH_UNION_UNCERTAIN' "Branch outcomes cannot be uniquely merged for $($entry.Class).$($entry.Method)." $entry.File
+        }
+        $result.Add([pscustomobject]$item)
+    }
+    $aggregate = Get-CoverageMeasure $classLines
+    $aggregateScope = 'class-lines'
+    if (-not $allClassesHaveLines -or -not $classLines.Count) {
+        $aggregateScope = if ($reports.Count -eq 1) { 'report' } else { 'method-lines-only' }
+        $aggregate = [pscustomobject]@{ LineCoverage = $null; LineCoverageStatus = 'unknown'; BranchCoverage = $null; BranchCoverageStatus = 'unknown' }
+        if ($reports.Count -eq 1) {
+            foreach ($metric in @('line', 'branch')) {
+                $counter = $reports[0][$metric]
+                $name = if ($metric -eq 'line') { 'LineCoverage' } else { 'BranchCoverage' }
+                if ($null -ne $counter) {
+                    $aggregate.$name = if ($counter.Total) { [math]::Round(100.0 * $counter.Covered / $counter.Total, 1) } else { $null }
+                    $aggregate."${name}Status" = if ($counter.Total) { 'exact' } else { 'not-applicable' }
+                }
+            }
+        }
+    }
+    if (-not $result.Count) {
+        Add-CoverageDiagnostic $diagnostics 'METHODS_UNAVAILABLE' 'The report has no method-level coverage evidence.' ''
+    }
+    return [pscustomobject]@{
+        Methods = @($result | Sort-Object -CaseSensitive Module, File, Class, Method, Signature)
+        Inputs = @($inputs)
+        Diagnostics = $diagnostics
+        Summary = [ordered]@{
+            overall_line_coverage = $aggregate.LineCoverage
+            overall_line_coverage_status = $aggregate.LineCoverageStatus
+            overall_branch_coverage = $aggregate.BranchCoverage
+            overall_branch_coverage_status = $aggregate.BranchCoverageStatus
+            coverage_scope = $aggregateScope
+            method_line_coverage = (Get-CoverageMeasure $methodLines).LineCoverage
+            total_methods = $result.Count
+        }
+    }
+}
+
+function Write-CoverageJson([string]$Tool, [string]$Status, $Scope, $Inputs, $Diagnostics, $Data) {
+    [ordered]@{
+        schema_version = '1'; tool = $Tool; tool_version = '1.0'; status = $Status
+        scope = $Scope; inputs = @($Inputs); diagnostics = @($Diagnostics); data = $Data
+    } | ConvertTo-Json -Depth 30
+}
+
+function Write-CoverageDiagnostics($Diagnostics) {
+    foreach ($diagnostic in $Diagnostics) {
+        [Console]::Error.WriteLine("$($diagnostic.code): $($diagnostic.message)")
+    }
+}

package/package/corpus/skills/coverage-analysis/scripts/Extract-MethodCoverage.ps1

@@ -0,0 +1,65 @@
+<#
+.SYNOPSIS
+Extract Cobertura method coverage without inventing missing measurements.
+.DESCRIPTION
+Legacy output is a JSON array; diagnostics and summaries go to stderr.
+Use -OutputFormat json-v1 for provenance, null/unknown metrics and branch bounds.
+Merging is scoped to reported module/file/class/signature identities, not an
+attestation of source revision. Duplicate report bytes are idempotent.
+Exit codes: 0 complete, 2 invalid input, 3 incomplete/unrepresentable evidence.
+#>
+param(
+    [Parameter(Mandatory=$true)][string[]]$CoberturaPath,
+    [ValidateRange(0,100)][int]$CoverageThreshold = 80,
+    [ValidateRange(0,100)][int]$BranchThreshold = 70,
+    [ValidateSet('uncovered', 'below-threshold', 'all')][string]$Filter = 'all',
+    [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 = 'Extract-MethodCoverage'; 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; filter = $Filter }
+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 'Extract-MethodCoverage' 'error' $scope @() $diagnostics @{} }
+    exit 2
+}
+$partial = -not $coverage.Methods.Count -or @($coverage.Methods | Where-Object {
+    $_.LineCoverageStatus -eq 'unknown' -or $_.BranchCoverageStatus -in @('unknown', 'bounded') -or $_.ComplexityStatus -eq 'unknown'
+}).Count -gt 0
+$methods = @($coverage.Methods | Where-Object {
+    if ($Filter -eq 'all') { return $true }
+    if ($_.LineCoverageStatus -eq 'unknown' -or $_.BranchCoverageStatus -in @('unknown', 'bounded')) { return $true }
+    if ($Filter -eq 'uncovered') { return $_.LineCoverage -eq 0 }
+    return (100.0 * $_.CoveredLines / $_.TotalLines) -lt $CoverageThreshold -or
+        ($_.TotalBranches -gt 0 -and (100.0 * $_.CoveredBranches / $_.TotalBranches) -lt $BranchThreshold)
+} | Sort-Object -Property @{Expression='UncoveredLines';Descending=$true}, @{Expression='LineCoverage';Descending=$false}, Class, Method, File, Signature)
+Write-CoverageDiagnostics $coverage.Diagnostics
+if ($OutputFormat -eq 'json-v1') {
+    Write-CoverageJson 'Extract-MethodCoverage' $(if ($partial) { 'partial' } else { 'complete' }) $scope $coverage.Inputs $coverage.Diagnostics @{
+        methods = $methods; summary = $coverage.Summary
+    }
+} elseif (-not $partial) {
+    $legacy = @($methods | Select-Object Class, Method, Signature, File, Complexity, LineCoverage,
+        @{Name='BranchCoverage';Expression={if ($_.BranchCoverageStatus -eq 'not-applicable') { 0 } else { $_.BranchCoverage }}},
+        CoveredLines, TotalLines, UncoveredLines, CoveredBranches, TotalBranches)
+    ConvertTo-Json -InputObject $legacy -Depth 5
+    [Console]::Error.WriteLine("METHODS_FILTERED:$($methods.Count)")
+    [Console]::Error.WriteLine("UNCOVERED_METHODS:$(@($methods | Where-Object { $_.LineCoverageStatus -eq 'exact' -and $_.LineCoverage -eq 0 }).Count)")
+}
+if ($partial) { exit 3 }
+exit 0

package/package/corpus/skills/cratis-ci-pipeline-performance/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the canonical Cratis/AI repository for the full license text.

package/package/corpus/skills/cratis-ci-pipeline-performance/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: cratis-ci-pipeline-performance
+description: Make a Cratis repository's GitHub Actions CI/CD faster and cheaper by measuring workflow timings first, picking the lever that fits the measured bottleneck (build once and shard, caching, path filters with an aggregator, concurrency, runner routing, publish from artifacts) and verifying before and after. Use when a workflow is slow, queues, burns runner minutes, reruns or cancels a lot, or when editing .github/workflows to speed up CI. Not for authoring a release (use cratis-governed-release-methodology), recurring regressions on one surface (use cratis-engineering-regression-cluster), runtime performance of application code (use cratis-performance-review), or fixing a red build.
+license: LICENSE
+---
+
+# Measure the workflow, then pick the lever
+
+A workflow is slow for one of four different reasons, and each has a different
+fix. Adding runners cures a queue and does nothing for a serial build; a faster
+build does nothing for a workflow that fails a quarter of the time. Measure,
+classify, change one lever, measure again. Never optimize from the YAML alone.
+
+Capacity, timeout, concurrency and runner invariants live in
+[github-actions.md](../../rules/github-actions.md); obey them and do not restate them in a change.
+Workflow-only pull requests carry the `no-release` label per
+[pull-requests.md](../../rules/pull-requests.md).
+
+## 1. Measure first
+
+Execute the bundled script (needs `gh` authenticated for the repository, and `jq`):
+
+```bash
+bash scripts/ci-timings.sh --repo OWNER/REPO --workflow ci.yml --limit 50 --jobs 10
+```
+
+Add `--branch main` or `--event pull_request` to compare populations; PR and
+default-branch runs behave differently. `bash scripts/ci-timings.sh --self-test`
+proves the script itself works without network access. Exit codes: `0` report
+printed, `2` usage error, `3` no runs or no data, `4` missing `gh`/`jq` or `gh`
+not authenticated. Exit `3` and `4` are an unknown, not a clean workflow: say the
+measurement was not made.
+
+The report separates **wall clock** (what a developer waits for) from
+**runner-minutes** (what the organization pays for or occupies). A change can
+cut one and raise the other; report both. It prints a one-line classification:
+
+| Class | Hint threshold | Meaning | First lever |
+|---|---|---|---|
+| failure-bound | failed or rerun >= 15% of completed runs | Time and minutes go into runs that are redone | Flaky and hung jobs; fail fast |
+| cancel-bound | cancelled >= 20% | Superseded work still ran heavy legs | Cheap gate first, path filters, smaller PR matrix |
+| queue-bound | median longest job wait >= 25% of wall | Jobs wait for runners, not for work | Fewer, bigger jobs; runner routing |
+| execution-bound | none of the above | The critical path is serial work | Build once and shard; caching |
+
+The thresholds are a hint, not a verdict. Several classes can hold at once; the
+script lists extras after the primary class. Then find the **critical path over
+the required checks**: the longest chain of `needs` from the start to the last
+required job. Only work on that chain shortens wall clock; shaving a parallel
+sibling does not.
+
+Without `gh` access, read the workflow YAML, state that the result is
+**static-only analysis**, and rank findings as hypotheses to measure later.
+
+## 2. Guardrails before proposing a fix
+
+- **Never hide required validation.** Release, schema, migration, analyzer and
+  shared-library checks stay on the path that gates a merge or a release. Moving
+  them to a schedule needs an explicit owner decision, not an optimization.
+- **Say what less parallelism costs.** Merging jobs lowers queue and setup cost
+  but lengthens the critical path when the merged work was parallel. State the
+  expected wall change and runner-minute change together.
+- **Separate repository changes from organization settings.** Workflow YAML is a
+  repository change. Runner capacity, scale sets and plan limits are not; report
+  them as a request to the owner and do not work around them in YAML.
+- **One lever per change.** Two levers at once make the measured difference
+  unattributable.
+- **Rank by what it saves.** Estimate minutes per day as (saving per run) x
+  (runs per day) from the report, and take the top one to three items.
+
+## 3. Lever catalogue
+
+Each lever lists when it fits, the Cratis default and the main pitfall. Read the
+named reference before applying one.
+
+**Build once, shard the tests.** Fits execution-bound workflows where build and
+tests run serially or several jobs each rebuild. Default: one job builds in
+`Release`, uploads the output with `actions/upload-artifact`, and a matrix of shard jobs downloads it and runs
+`dotnet test --no-build`. Pitfall: a shard whose filter matches nothing still
+passes, so assert that every shard ran tests. Read
+`references/build-once-and-shard.md` when applying or reviewing this.
+
+**Fewer, bigger jobs.** Fits queue-bound workflows: every job pays a scheduler
+start, checkout and toolchain setup. Default: merge small sibling jobs that share
+a setup; keep shards only where the work is long enough to repay a start. Pitfall:
+merging the long pole into a serial chain. Read `references/build-once-and-shard.md`.
+
+**Dependency caching.** Fits any job with a measurable restore or install step.
+Default: the shared `Cratis/Workflows` composite actions `dotnet-cache` and
+`yarn-cache` (restore on pull requests, save on the default branch), NuGet lock files and
+`yarn install --immutable`. Pitfall: a cache key that changes every run, or a
+different path list per workflow, which creates separate caches. Read
+`references/caching.md`.
+
+**Docker layer cache.** Fits image builds that repeat unchanged layers. Default:
+`docker/build-push-action` with `cache-from`/`cache-to` of type `gha` and a custom
+`scope` per image and platform. Pitfall: the default scope is shared, so builds
+overwrite each other's cache. Read `references/caching.md`.
+
+**Path filters with an always-run aggregator.** Fits cancel-bound workflows and
+documentation-only changes. Default: filter heavy jobs by changed paths, and make
+a single aggregator job with `if: always()` check every `needs.*.result`; require
+only the aggregator. Pitfall: a required check skipped by `paths:` never reports
+and the pull request hangs. Read `references/required-checks-and-path-filters.md`.
+
+**Concurrency.** Pull-request verification uses `cancel-in-progress: true` keyed
+by workflow and ref. Publish never cancels; where releases share one group, `queue:
+max` keeps up to 100 pending runs in order instead of replacing the single pending
+one. Pitfall: leaving the single pending slot where a replaced merge's run alone
+would have released something (merges into the default branch share a group, also
+when keyed on `github.ref` for merged `pull_request` `closed` events). A workflow
+whose release tooling aggregates since the last release may keep one pending slot,
+documented. Read `references/publish-pipelines.md`.
+
+**Runner routing.** Fits queue-bound workflows. Default: private-repository jobs
+on the organization scale set `cratis-arc` or a repository variable that falls
+back to a hosted label, hosted runners for public repositories. Pitfall: never
+route `pull_request` jobs of a public repository to self-hosted runners; that is
+fork code on our infrastructure. The rule owns the details.
+
+**Publish from tested artifacts.** Fits release workflows that rebuild what the
+pull-request run already built and tested. Default: build and pack once, then
+publish exactly those packages. Pitfall: a second build can differ from the
+tested one. Read `references/publish-pipelines.md`.
+
+**Fail fast on cheap gates.** Fits failure-bound and cancel-bound workflows.
+Default: formatting, lint and unit-level checks run first, and expensive legs
+depend on them with `needs`. Pitfall: serializing checks that were parallel; keep
+the cheap gate short enough to repay its place on the critical path.
+
+**Expensive matrices off the PR path.** Fits cancel-bound workflows with a wide
+OS or framework matrix. Default: full matrix on `schedule` and
+`workflow_dispatch`, a Linux-only representative smoke on pull requests (the
+rule states this). Pitfall: the full matrix needs an owner who reads its failures.
+
+**Flaky and hung jobs.** Fits failure-bound workflows. Default: a
+`timeout-minutes` on every job, `--blame-hang`, retry only a diagnosed flake, and
+quarantine a test with an issue. Pitfall: a blanket rerun hides the defect and
+doubles minutes. Read `references/flaky-and-hung-jobs.md`.
+
+**Merge queue.** Fits repositories where passing pull requests break each other
+after merge. Default: add the `merge_group` trigger, and make the aggregator
+handle it. Pitfall: without `merge_group` the required check never reports in the
+queue. Read `references/required-checks-and-path-filters.md`.
+
+**Compile once, analyze once.** Fits any workflow where one push compiles the same
+code several times. Default: build once and reuse the output; run analyzers in one
+parallel lint job instead of in every build, and let that job fail early on compile
+and analyzer errors before long test legs. Pitfall: dropping analyzers from the only
+build that consumers enforce. Read `references/test-setup-cost.md`.
+
+**Cores per job before job count.** Fits uniformly slow jobs. Default: check `nproc`
+and the runner's resources before sharding; undersized runners make every job slow.
+Pitfall: adding jobs to an undersized pool. Read `references/runner-sizing-and-images.md`.
+
+**Hidden test setup.** Fits test lanes whose step time far exceeds the runner's
+reported test time. Default: profile the test host and fix per-class setup upstream
+rather than sharding it. Pitfall: sharding that divides the waste. Read
+`references/test-setup-cost.md`.
+
+**Test a guarantee where it can break.** Fits suites that re-test a dependency.
+Default: run them upstream, or on a dependency pin change or nightly; use snapshots
+for shape and post-deploy synthetic checks where possible. Pitfall: relocating the
+only check of a required guarantee. Read `references/test-setup-cost.md`.
+
+**Images and runner contents.** Fits jobs that pull unused images or install tools per
+run. Default: pull only what the job uses, in parallel, and bake tools into the runner
+image; content-addressed caches before warm volumes, publish stays cold. Read
+`references/runner-sizing-and-images.md`.
+
+Speed work must not weaken supply-chain hygiene. Read
+`references/security-and-pinning.md` when a change adds or updates an action,
+touches `permissions:`, uses `pull_request_target`, or adds a cache.
+
+## 4. Verify
+
+1. Re-run the same `ci-timings.sh` command on the same workflow after enough new
+   runs exist (at least the sample size of the baseline; say so when fewer).
+2. Report expected against measured savings, wall and runner-minutes separately,
+   and whether the classification moved. A saving that is not measured is labeled
+   as expected.
+3. Run the linters locally on every edited workflow when installed: `actionlint`
+   (syntax, expressions, embedded shell) and `zizmor` (security audits such as
+   `unpinned-uses` and `excessive-permissions`). Pass means exit `0` with no
+   findings; a tool that is not installed is reported as not run, not as clean.
+   Do not assume CI runs either.
+4. Compare required check names before and after; a renamed job silently removes
+   a required check. See `references/required-checks-and-path-filters.md`.
+5. Confirm the workflow change ships as `no-release`.
+
+## References
+
+- Read `references/build-once-and-shard.md` when changing how a build is shared across jobs or how tests are split.
+- Read `references/caching.md` when adding or changing a dependency, Docker or build cache.
+- Read `references/required-checks-and-path-filters.md` when adding path filters, an aggregator, or `merge_group`.
+- Read `references/publish-pipelines.md` when a release or deploy workflow queues, drops runs or rebuilds.
+- Read `references/flaky-and-hung-jobs.md` when runs fail, hang or are rerun.
+- Read `references/test-setup-cost.md` when test steps outlast reported test time, tests duplicate a dependency's suite, or compiles repeat per push.
+- Read `references/runner-sizing-and-images.md` when jobs are uniformly slow, pull images, install tools or reuse workspaces.
+- Read `references/security-and-pinning.md` when a change touches actions, permissions, triggers or caches.
+- Read `references/sources.md` when attributing or extending the method.
+- Execute `scripts/ci-timings.sh` for every measurement; read it only to change it. Its self-test reads the synthetic inputs `scripts/fixtures/runs.json` and `scripts/fixtures/jobs/1003.json`, `scripts/fixtures/jobs/1007.json`, `scripts/fixtures/jobs/1010.json`; edit them only together with the expected lines in the script.