@cratis/pi 7.102.0 → 7.103.1

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-screenplay-command-surface/SKILL.md

@@ -121,7 +121,32 @@ At most one command property may carry `identifier`. It names the value the
 runtime uses as the event source id, so **choosing it is choosing the stream
 boundary** — the highest-consequence decision in the slice. Leave it out only
 when the runtime should allocate a fresh `Uuid` (a command that creates
-something whose identity the caller does not supply).
+something whose identity the caller does not supply); for a create command prefer
+`generated identifier` below, which also keeps the id out of the rendered form.
+
+**A command that creates something has no caller-supplied id.** Declare
+`<id> <IdConcept> generated identifier` (ESM v7, Screenplay 4.68.0 or later) and `returns <id>` when the
+caller needs it back. Symptom of getting it wrong: `organizationId OrganizationId identifier` on a create
+command makes the rendered form ask the user to type an Organization Id. Keep plain `identifier` for
+commands that act on an existing stream (the id comes from the selected row). Specifications pin the
+allocated value with `for "<value>"` in `when` and `then` (see the generated-values reference). Read
+[generated values](references/generated-values-and-responses.md) before writing one.
+
+```screenplay excerpt
+command RegisterOrganization
+  organizationId OrganizationId generated identifier
+  name           OrganizationName
+  produces event OrganizationRegistered
+    name OrganizationName = name
+  returns organizationId
+specification RegistersAnOrganization
+  when RegisterOrganization
+    for "11111111-1111-1111-1111-111111111111"
+    name = "Acme"
+  then OrganizationRegistered
+    for "11111111-1111-1111-1111-111111111111"
+    name = "Acme"
+```
 
 - A second `identifier` on the same command is an error: *only one property can be
   the identifier*.

package/package/corpus/skills/cratis-screenplay-projections/SKILL.md

@@ -282,6 +282,23 @@ of a document a reader cannot check at a glance.
 
 Read [pdl-grammar.md](references/pdl-grammar.md) when checking exact syntax, interpreting a projection diagnostic code, or needing a worked example.
 
+## `STAGE-ESM-017` on a projection passes `validate` and fails at `render`
+
+Symptom: `cratis screenplay validate --executable` exits 0, then `cratis render` (or `render --check`)
+refuses with `STAGE-ESM-017` and a generic message whose location is a `sem1:<hash>`, not a source line
+(seen on Stage 4.192.0 and CLI 3.94.0). Cause: `validate --executable` binds only Screenplay's model;
+Stage's admission runs only in `render`. Check every `from` block in turn:
+
+1. **Key.** An event property or the event source. A root `from` also accepts a constant text key (nonempty, only letters, digits, `_`, space and `. / : * + -`); any other literal key, and a literal key outside a root, is refused.
+2. **Do not overwrite the key.** A mapping onto the key property must restate the key itself (`from E` keyed by the event source with `berthId = $eventSourceId`, or the key's own event property); mapping a different value onto it is refused (`MatchesKey`). Simplest is to leave the key property unmapped.
+3. **`$eventSourceId` into a non-key target** is admitted in a `from` block keyed by an event property, when every command and reaction producing the event addresses it with a non-collection value of exactly the target's type (optionality ignored). It is refused in `join`s, for a mismatched type, and for an event nothing produces.
+4. **No `$context.*`.** Map an event property instead and have the command set it. The compiler may refuse it first (`PLAY0152`); Stage refuses a context value in a projection with `STAGE-ESM-017`.
+5. **Targets.** A target path through an optional or non-composite intermediate is refused; an optional leaf and a path through required composites are fine. The event property mapped from must exist on the event.
+
+Bisect: run `cratis render <root> --target cratis --name <App> --destination <dir> --check` (plans,
+writes nothing), comment out `from` blocks one at a time until the error clears, then apply the list to
+the block that cleared it. Reference: `cratis-stage-rendering-and-sandbox` `references/admission.md`.
+
 ## Verify
 
 - [ ] Standalone `screenplay <model> --warnaserror` reports zero errors and zero

package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/SKILL.md

@@ -178,6 +178,23 @@ Adapters and non-renderable scope follow the contract rules of `cratis-applicati
   Never `.cratis-render/` (the journal directory) and never `.ai-work/`.
 - Limits stated in this text are prompt policy unless a guard enforces them; say so.
 
+## Hand-written query logic and re-render
+
+Symptom: a today-relative query (overdue, due today) was written by editing the body of a generated query
+file; the next `render` refused with `Managed artifact '<file>' was modified by the user; pass --force to
+replace it.` Query filters are equality only and there is no `today` in a filter or projection, so this
+logic is gap-fill. Cause: a managed file's hash is in `.cratis-render.json`, and an edited one blocks the
+whole re-render. What to do:
+
+- Never edit a managed file. Put the logic in a new unmanaged file, for example `Customizations/<Name>.cs`
+  (compiled with the project, never replaced by `render`), with its own endpoint or query class, and record it
+  as gap-fill (`references/gap-fill-handoff.md`).
+- `--force` replaces the edited managed file with the generated one and discards the edit; use it only with
+  approval that names the file.
+- Screens reported as `PLAY0269` are information that the backend profile defers them. They are not
+  proof of a rendered screen: check the running app (`cratis-screenplay-toolchain` `references/fast-path.md`)
+  and list any authored screen that is missing as not rendered.
+
 ## Gate
 
 Before reporting done:

package/package/corpus/skills/cratis-screenplay-specifications/SKILL.md

@@ -277,11 +277,19 @@ For view specifications:
 - [ ] Queries cover out-of-rule concept arguments with `then error`; a valid
       absent key uses `then no result`. Projections still cannot reject events.
 
+## Run the specs before calling the work done
+
+Symptom: a model delivered with specifications that were never run. `screenplay test <root>` runs the
+reference evaluator; after a render, run `dotnet test` (Debug) in the destination for the generated
+specification classes. Report both results separately (`cratis-screenplay-toolchain` V4 and V5.tests); a
+build that succeeds is not a test run, and `unbound`/`unsupported` is not a pass.
+
 ## Verify
 
 - [ ] Validate the complete root with warnings as errors, naming tool/version.
       Standalone tool version: `cratis-screenplay-toolchain/SKILL.md`. Run specification examples through
       `screenplay test`; expected unadmitted syntax reports unbound, not passed.
+- [ ] `screenplay test` and, after a render, `dotnet test` were run and their counts reported.
 - [ ] Executable diagnostics are clean too: `PLAY0350`, `PLAY0352`, `PLAY0388`,
       `PLAY0389` and `PLAY0273` are only reported at binding.
 - [ ] Every slice has at least one boundary specification.

package/package/corpus/skills/cratis-screenplay-toolchain/SKILL.md

@@ -218,7 +218,7 @@ unresolved questions: the standalone tool has `--open-questions fail`; `cratis s
 does through `--open-questions report|fail`. It is separate from compilation and `--warnaserror`.
 Requires Cratis CLI 3.60.0 or later (`cratis --version`) for that option; older CLIs lack it.
 
-Read [fast path](references/fast-path.md) for the ordered requirements-to-running-app checklist (validate, `render --check`, render, build, run).
+Read [fast path](references/fast-path.md) for the ordered requirements-to-running-app checklist (validate, `render --check`, render, build, run, check in a browser, run the specs).
 
 ## Route near misses
 

package/package/corpus/skills/cratis-screenplay-toolchain/references/cheat-sheet-example.md

@@ -171,6 +171,7 @@ module Billing
         table InvoiceRow
           column number label "Number"
         action RegisterInvoice
+          label "Register invoice"
       specification ListingAnInvoice
         given caller                                  // module + feature gates apply to the query too
           authenticated

package/package/corpus/skills/cratis-screenplay-toolchain/references/fast-path.md

@@ -20,5 +20,12 @@ Run these in order and stop at the first failure; each step catches what the one
 8. **Frontend:** in `<dir>`, `yarn` then `yarn dev` (npm: `npm install`, `npm run dev`); open the URL Vite
    prints. It proxies API calls to the backend.
 
+9. **Verify in a browser:** open the Vite URL, load every screen the model authored (sidebar and each screen title),
+   run one create command and one query, and read the console for errors. The check is the app, not the build:
+   a screen reported as `PLAY0269` (deferred from the backend profile, information only) is not evidence that
+   it was rendered. List any authored screen that is absent as not rendered; do not call it delivered.
+10. **Specs:** `dotnet test` in `<dir>` (the generated specifications) and `screenplay test <root>`; see
+    `cratis-screenplay-specifications`.
+
 The rendered `README.md` repeats steps 6-8 for the pinned scaffold. Re-render and gap-fill rules:
 `cratis-screenplay-render-and-gap-fill`.

package/package/corpus/skills/cratis-screenplay-toolchain/references/traps.md

@@ -72,3 +72,4 @@ Traps 39 to 44 are tool traps.
 45. A reducer cannot be re-keyed: its instances follow the event-source id, so a query `by` another identity type warns PLAY0690 (`--warnaserror` fails it; editors only show it when the host supplies native findings). Aggregate by a payload value with a projection keyed on each `from`, or a join: projections [reducer identity](../../cratis-screenplay-projections/references/reducer-identity.md).
 46. Enum members are lowercase identifiers (`hourly`, not `Hourly`; PLAY0009). A specification states every property of the command and events, optional ones too (PLAY0524). A read model with two `*Id` properties needs one keyed query, `query OrderById => Order optional` with `by orderId String` (PLAY0268 otherwise). A `require` message goes on the next indented line (trap 38). Screen list queries are `observable`.
 47. Cratis events have no optional properties (STAGE-ESM-005), and `validate --executable` does not catch it: run `cratis render <folder> --target cratis --name <App> --destination <dir> --check` right after validate, since it runs the renderer's admission and writes nothing.
+48. `STAGE-ESM-017` on a projection also passes `validate --executable` and shows only a `sem1:` location, not the `from` block. Run `render --check` after validate, then follow the checklist and bisect in projections `SKILL.md` ("`STAGE-ESM-017` on a projection").

package/package/corpus/skills/cratis-screenplay-ui-composition/SKILL.md

@@ -270,6 +270,44 @@ precedence, PLAY0485 and examples.
 
 A `ui profile` selects the application shell with `root template` (an own layout or application-scope screen template, or `blueprint <B> <Name>` with an optional `version` pin), its shell `option` lines, an `appearance` block (`color scheme`, `accent`), the template new screens start from (`new screens use template`), the theme and the `packages`, listed in override-priority order (a later package shadows an earlier one); `target platform` and `target size` accept any identifier, so a typo is silent. The legacy `layout <Name>` line inside a profile still reads but warns `PLAY0791`: write `root template`. `PLAY0790` to `PLAY0799` check the shell. Read [references/ui-profile-and-theme.md](references/ui-profile-and-theme.md) when writing a profile or theme, or fixing a shell diagnostic.
 
+## A deliverable app declares its identity, titles and labels
+
+Symptom: a rendered app titled "Cratis Stage" whose buttons and dialogs show raw command names. The renderer
+defaults to those when the model is silent, so declare, in every deliverable app:
+
+- the layout's `logo image "<path>" title "<text>"` inside `navigation topbar` or `navigation sidebar` (the
+  application title the shell shows; `logo initials` is only valid in a profile's `identity`);
+- a `ui profile` with `root template`, shell `option` lines such as `option showFooter false`, and an `identity`
+  block (`name`, `logo initials`);
+- a `title "<text>"` in each screen and a navigation `item <id> title "<text>" target <Module.Feature>` per screen;
+- `label "<text>"` on **every** `action`.
+
+```screenplay excerpt
+layout AppShell
+  category application
+  content
+
+  navigation sidebar
+    logo image "/assets/solocrm.svg" title "SoloCRM"
+    item organizations title "Organizations" target Crm.Organizations
+
+ui profile Desktop
+  target platform web
+  root template AppShell
+    option showFooter false
+  identity
+    name "SoloCRM"
+    logo initials "SC"
+```
+
+```screenplay excerpt
+screen Organizations
+  data OrganizationOverview[] via query AllOrganizations
+  title "Organizations"
+  action RegisterOrganization
+    label "New organization"
+```
+
 ## Localized strings
 
 Localized text lives in companion `.strings` files and is referenced unquoted as `$strings.<dotted.key>`. Read [references/localized-strings.md](references/localized-strings.md) when localizing messages, labels or titles.
@@ -294,6 +332,8 @@ Localized text lives in companion `.strings` files and is referenced unquoted as
 - [ ] Every theme a profile selects is `compatible with` one of its packages.
 - [ ] `target platform` and `target size` values are spelled correctly; nothing
       checks them.
+- [ ] A deliverable app declares layout `logo ... title`, a `ui profile` with `option` lines and `identity`,
+      a `title` per screen and a `label` on every `action`.
 - [ ] User-visible text is `$strings.` where the application is localized.
 - [ ] No `file` reference is doing work the declaration should be doing.
 - [ ] Every click, submit and screen entry that does something has an `on` or

package/package/corpus/skills/cratis-screenplay-ui-composition/references/response-continuations.md

@@ -73,6 +73,7 @@ module Billing
         returns invoiceId
       screen CreateInvoiceScreen
         action CreateInvoice
+          label "Create invoice"
     slice StateView Details
       readmodel Invoice
         invoiceId InvoiceId

package/package/corpus/skills/cratis-screenplay-ui-composition/references/worked-flow.md

@@ -23,6 +23,7 @@ module Marina
         data BerthListView[] via query ListBerths
         action BookBerth
           navigate to BerthListScreen
+          label "Book berth"
     slice StateView BerthList
       readmodel BerthListView
         berthId BerthId

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/admission.md

@@ -251,8 +251,9 @@ Stage renders two projection forms; the restrictions differ.
   inside a child are admitted), `nested`
   over an optional composite property, and `every`/`all` with set-from-event-source mappings. Keys
   are an event property or the event source. The key establishes the identifier, so it must
-  end up unmapped: a mapping onto it is refused unless it copies the key's own event
-  property, so an event-source key admits no mapping at all (`STAGE-ESM-017`). Auto-map
+  end up unmapped: a mapping onto it is refused unless it restates the key (the key's own
+  event property, `$eventSourceId` for an event-source key, or the same literal)
+  (`STAGE-ESM-017`). Auto-map
   counts as a mapping: if the event carries a property with the identifier's name and type,
   declare `no automap` and map the other properties explicitly. `from E` and
   `from E key $eventSourceId` render when the identifier ends up unmapped, whether or not

package/package/corpus/skills/csharp-refactoring/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/csharp-refactoring/NOTICE

@@ -0,0 +1,22 @@
+C# Refactoring (behavior-preserving)
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet/skills/csharp-refactoring/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line.
+- Add the requested Cratis persisted-event, proxy, Orleans identity and framework-public-API contract section.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+- Remove references to the dotnet-upgrade skill; point to the repository's own upgrade workflow.
+
+references/operation-catalog.md:
+- Replace the upstream issue reference with a plain statement of the behavior.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.