@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/hooks/scripts/cratis-guard-writes.sh

@@ -18,23 +18,74 @@ set -euo pipefail
 
 # SCRIPTDIR, not a path relative to the caller: shellcheck resolves a plain relative `source=`
 # against the current working directory, and these hooks are linted from wherever CI happens to run.
+script_directory="${BASH_SOURCE[0]%/*}"
+[ "$script_directory" != "${BASH_SOURCE[0]}" ] || script_directory=.
 # shellcheck source=SCRIPTDIR/hook-lib.sh
-. "$(dirname "${BASH_SOURCE[0]}")/hook-lib.sh"
+. "$script_directory/hook-lib.sh"
 
 [ "${CRATIS_HOOKS_ALLOW_PROTECTED_WRITES:-0}" = "1" ] && exit 0
 
-input="$(hook_read_stdin)"
+# This guard runs before every write, so it avoids subprocesses where a builtin does the same job:
+# the helpers below return through REPLY instead of printing into a command substitution.
+# Read stdin with the read builtin: opening /dev/stdin fails with ENXIO when stdin is a socket (Linux, Node pipes).
+input=""
+IFS= read -r -d '' input || true
 [ -n "$input" ] || exit 0
 hook_have jq || exit 0
 
-root="$(hook_repo_root)"
-cwd="$(hook_json "$input" '.cwd')"
-[ -n "$cwd" ] || cwd="$root"
+# One jq call reads every field the guard uses. Fields are NUL-terminated (embedded NULs are dropped,
+# as a command substitution would drop them); a missing, null, false or unreadable path is empty.
+cwd="" file="" notebook="" new_content="" new_string=""
+{
+    IFS= read -r -d '' cwd
+    IFS= read -r -d '' file
+    IFS= read -r -d '' notebook
+    IFS= read -r -d '' new_content
+    IFS= read -r -d '' new_string
+} < <(jq -j '
+    def field(path): ([try (path // empty) catch empty] | first // "")
+        | if type == "string" then . else tojson end
+        | gsub("\u0000"; "");
+    [field(.cwd), field(.tool_input.file_path), field(.tool_input.notebook_path),
+     field(.tool_input.content), field(.tool_input.new_string)]
+    | .[] | ., "\u0000"
+' <<<"$input" 2>/dev/null) || true
+# Command substitution stripped trailing newlines from each field; keep that behaviour.
+for field_name in cwd file notebook new_content new_string; do
+    while [[ "${!field_name}" == *$'\n' ]]; do printf -v "$field_name" '%s' "${!field_name%$'\n'}"; done
+done
 
-file="$(hook_json "$input" '.tool_input.file_path')"
-[ -n "$file" ] || file="$(hook_json "$input" '.tool_input.notebook_path')"
+[ -n "$cwd" ] || cwd="$(hook_repo_root)"
+[ -n "$file" ] || file="$notebook"
 [ -n "$file" ] || exit 0
 
+# dir_of / base_of / relative_to mirror dirname, basename and hook_relpath for the absolute,
+# normalized paths used here. abspath mirrors hook_abspath. All return through REPLY.
+dir_of() {
+    REPLY="${1%/*}"
+    [ -n "$REPLY" ] || REPLY=/
+}
+
+base_of() {
+    REPLY="${1##*/}"
+    [ -n "$REPLY" ] || REPLY=/
+}
+
+abspath() {
+    case "$1" in
+        /*) REPLY="$1" ;;
+        *) REPLY="${2%/}/$1" ;;
+    esac
+}
+
+relative_to() {
+    local root="${2%/}"
+    case "$1" in
+        "$root"/*) REPLY="${1#"$root"/}" ;;
+        *) REPLY="$1" ;;
+    esac
+}
+
 # Lexically normalize before any Git lookup or parent walk, including nonexistent segments.
 # Component parsing preserves spaces and glob characters without depending on realpath.
 normalize_target_path() {
@@ -52,17 +103,22 @@ normalize_target_path() {
             *) normalized="$normalized/$component" ;;
         esac
     done
-    printf '%s\n' "${normalized:-/}"
+    REPLY="${normalized:-/}"
 }
 
-file="$(hook_abspath "$file" "$cwd")"
-file="$(normalize_target_path "$file")"
-# Pi can run the bundled script in a consumer checkout; this root is only for diagnostics.
-root="$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || printf '%s\n' "$cwd")"
-rel="$(hook_relpath "$file" "$root")"
-base="$(basename "$file")"
+abspath "$file" "$cwd"
+normalize_target_path "$REPLY"
+file="$REPLY"
+base_of "$file"
+base="$REPLY"
 
 block() {
+    # Pi can run the bundled script in a consumer checkout; this root is only for diagnostics,
+    # so it is looked up only when a write is actually refused.
+    local root rel
+    root="$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null || printf '%s\n' "$cwd")"
+    relative_to "$file" "$root"
+    rel="$REPLY"
     printf 'BLOCKED by cratis-guard-writes: %s\n\n%s\n\n%s\n' "$rel" "$1" "$2" >&2
     exit 2
 }
@@ -70,36 +126,70 @@ block() {
 # Check both the addressed path and its physical destination: settings may be symlinks to
 # templates, and an innocently named link may target a protected file. Preserve missing suffixes.
 physical_target_path() {
-    local target="$1" directory suffix="" link hops=0
+    local target="$1" directory suffix="" link hops=0 start="$PWD"
+    physical_file=""
     while [ -L "$target" ]; do
         hops=$((hops + 1))
         [ "$hops" -le 40 ] || return 1
         link="$(readlink "$target")" || return 1
-        target="$(hook_abspath "$link" "$(dirname "$target")")"
+        dir_of "$target"
+        abspath "$link" "$REPLY"
+        target="$REPLY"
     done
-    directory="$(dirname "$target")"
-    suffix="/$(basename "$target")"
+    dir_of "$target"
+    directory="$REPLY"
+    base_of "$target"
+    suffix="/$REPLY"
     while [ ! -d "$directory" ]; do
         [ "$directory" != "/" ] || return 1
-        suffix="/$(basename "$directory")$suffix"
-        directory="$(dirname "$directory")"
+        base_of "$directory"
+        suffix="/$REPLY$suffix"
+        dir_of "$directory"
+        directory="$REPLY"
     done
-    directory="$(cd -P "$directory" 2>/dev/null && pwd -P)" || return 1
-    printf '%s\n' "${directory%/}$suffix"
+    cd -P "$directory" 2>/dev/null || return 1
+    directory="$PWD"
+    cd "$start" 2>/dev/null || true
+    physical_file="${directory%/}$suffix"
+}
+
+# The origin URL, looked up once per repository per run.
+origin_cache_root=""
+origin_cache_value=""
+repository_origin() {
+    if [ "$origin_cache_root" != "$1" ]; then
+        origin_cache_value="$(git -C "$1" remote get-url origin 2>/dev/null || true)"
+        origin_cache_root="$1"
+    fi
+    REPLY="$origin_cache_value"
+}
+
+# Case-insensitive ASCII match of the origin URL, equivalent to grep -Eiq on a single line.
+origin_matches() {
+    # C locale, as the grep it replaced ran: a non-ASCII letter (the Kelvin sign) must not match [a-z].
+    local LC_ALL=C pattern="$1" matched=1
+    shopt -s nocasematch
+    # shellcheck disable=SC2034
+    [[ "$REPLY" =~ $pattern ]] && matched=0
+    shopt -u nocasematch
+    return "$matched"
 }
 
 # ── 4. Agent controls and installed managed trees ─────────────────────────────
 agent_control_target() {
-    local target="$1" directory policy_root target_rel origin
-    directory="$(dirname "$target")"
+    local target="$1" directory policy_root target_rel
+    dir_of "$target"
+    directory="$REPLY"
     # Keep the addressed spelling here, even when an adapter directory is a symlink.
     # .git is a directory in a checkout and a file in a linked worktree.
     while [ ! -e "$directory/.git" ]; do
         [ "$directory" != "/" ] || return 1
-        directory="$(dirname "$directory")"
+        dir_of "$directory"
+        directory="$REPLY"
     done
     policy_root="$directory"
-    target_rel="$(hook_relpath "$target" "$policy_root")"
+    relative_to "$target" "$policy_root"
+    target_rel="$REPLY"
     if [ -f "$policy_root/.cratis/ai.manifest.json" ]; then
         case "$target_rel" in
             .cratis/ai/*) return 0 ;;
@@ -122,8 +212,8 @@ agent_control_target() {
         esac
     else
         # The corpus is authored source in Cratis/AI, not a managed installation.
-        origin="$(git -C "$policy_root" remote get-url origin 2>/dev/null || true)"
-        if printf '%s\n' "$origin" | LC_ALL=C grep -Eiq '^(https://github\.com/|git@github\.com:|ssh://git@github\.com(:[0-9]+)?/)cratis/ai(\.git)?/?$'; then
+        repository_origin "$policy_root"
+        if origin_matches '^(https://github\.com/|git@github\.com:|ssh://git@github\.com(:[0-9]+)?/)cratis/ai(\.git)?/?$'; then
             return 1
         fi
     fi
@@ -134,7 +224,7 @@ agent_control_target() {
     return 1
 }
 
-physical_file="$(physical_target_path "$file" || true)"
+physical_target_path "$file" || physical_file=""
 if agent_control_target "$file" || { [ -n "$physical_file" ] && agent_control_target "$physical_file"; }; then
     block \
         "This target controls the agent's permissions or extensions, or belongs to an installed managed corpus/adapter tree. Agent Write/Edit calls may not alter their own controls or managed instructions." \
@@ -146,19 +236,30 @@ fi
 # Merely *mentioning* the string — documentation, a rule file, this corpus — is not a match.
 marker='^[[:space:]]*(//|/\*|#|<!--)[[:space:]]*@generated by Cratis'
 
+# True when one of the first five lines of stdin carries the marker (head -n 5 | grep -E, without forks).
+first_lines_carry_marker() {
+    local LC_ALL=C line count=0
+    while [ "$count" -lt 5 ] && { IFS= read -r line || [ -n "$line" ]; }; do
+        count=$((count + 1))
+        # shellcheck disable=SC2034
+        [[ "$line" =~ $marker ]] && return 0
+    done
+    return 1
+}
+
+# The cheap in-shell header test runs first; grep -I then confirms the file is text, as before.
 if [ -f "$file" ] \
-    && LC_ALL=C grep -Iq . "$file" 2>/dev/null \
-    && head -n 5 "$file" 2>/dev/null | LC_ALL=C grep -Eq "$marker"; then
+    && first_lines_carry_marker 2>/dev/null <"$file" \
+    && LC_ALL=C grep -Iq . "$file" 2>/dev/null; then
     block \
         "This file is generated output (its header marks it as generated by Cratis). Rule 15 [contract] in .cratis/ai/rules/general.md: never edit a generated file — the next build overwrites it." \
         "Instead: change the C# source it is generated from (the [Command] / [ReadModel] record) and rebuild with 'dotnet build -c Debug' to regenerate the proxy."
 fi
 
 # The same guard for authoring a *new* file that pretends to be generated output.
-new_content="$(hook_json "$input" '.tool_input.content')"
-[ -n "$new_content" ] || new_content="$(hook_json "$input" '.tool_input.new_string')"
+[ -n "$new_content" ] || new_content="$new_string"
 if [ -n "$new_content" ] \
-    && printf '%s\n' "$new_content" | head -n 5 | LC_ALL=C grep -Eq "$marker"; then
+    && first_lines_carry_marker <<<"$new_content"; then
     block \
         "The content being written opens with a Cratis generated-file header. Proxies are produced by the Cratis proxy generator, never hand-written." \
         "Instead: write the C# source and run 'dotnet build -c Debug' to generate the proxy."
@@ -166,16 +267,20 @@ fi
 
 # ── 2. Dependency manifests, lockfiles, SDK and NuGet configuration ───────────
 manifest_writes_allowed() {
-    local setting="" origin directory policy_root
+    local setting="" directory policy_root start="$PWD"
     # Authorization belongs to the write target, which may be outside the session's checkout.
     # New files can have nonexistent parents; find their nearest existing directory first.
-    directory="$(dirname "$file")"
+    dir_of "$file"
+    directory="$REPLY"
     while [ ! -d "$directory" ]; do
         [ "$directory" != "/" ] || return 1
-        directory="$(dirname "$directory")"
+        dir_of "$directory"
+        directory="$REPLY"
     done
     # Follow existing directory symlinks before asking Git which repository owns the target.
-    directory="$(cd -P "$directory" 2>/dev/null && pwd -P)" || return 1
+    cd -P "$directory" 2>/dev/null || return 1
+    directory="$PWD"
+    cd "$start" 2>/dev/null || true
     policy_root="$(git -C "$directory" rev-parse --show-toplevel 2>/dev/null)" || return 1
     if [ -f "$policy_root/.cratis/ai.json" ]; then
         # Only actual booleans override the default; jq's `// empty` would discard false.
@@ -185,9 +290,9 @@ manifest_writes_allowed() {
         true) return 0 ;;
         false) return 1 ;;
     esac
-    origin="$(git -C "$policy_root" remote get-url origin 2>/dev/null || true)"
+    repository_origin "$policy_root"
     # Anchor host, owner and the single repository segment; never infer ownership from profiles.
-    printf '%s\n' "$origin" | LC_ALL=C grep -Eiq '^(https://github\.com/|git@github\.com:|ssh://git@github\.com(:[0-9]+)?/)cratis/[a-z0-9_.-]+/?$'
+    origin_matches '^(https://github\.com/|git@github\.com:|ssh://git@github\.com(:[0-9]+)?/)cratis/[a-z0-9_.-]+/?$'
 }
 
 case "$base" in

package/package/corpus/rules/github-actions.md

@@ -44,6 +44,23 @@ paths:
   `cancel-in-progress: true`, keyed `${{ github.workflow }}-${{ github.ref }}`.
   **Never** cancel-in-progress on publish, release, or deploy workflows — a cancelled
   half-publish is worse than a queued one.
+- **Publish and release workflows never cancel** (`cancel-in-progress: false`) and set
+  `queue: max`. A group holds one running and one pending run; a newer arrival replaces
+  the pending one. Merges into the default branch share a group (a push, a repository-wide
+  key, or `github.ref` on a merged `pull_request` `closed` event, which is the base
+  branch), so without `queue: max` a newer merge replaces the older pending release.
+  `queue: max` keeps up to 100 pending runs, processed in order, and applies only while
+  `cancel-in-progress` is false or unset. Keep a single pending slot only for a documented
+  design where each run releases everything since the last release, so a replaced run
+  loses nothing; say so in a comment beside the `concurrency` block.
+- **A required check must not be skippable by `paths:` alone.** A workflow that never
+  starts never reports, and the pull request hangs. Gate jobs on a change-detection job
+  and require one always-run aggregator job (`if: always()`, checks every `needs.*.result`).
+- **Pin third-party actions by full commit SHA** (version in a comment) and set minimal
+  `permissions:` on each job. Run `zizmor` locally on edited workflows: its `unpinned-uses`
+  and `excessive-permissions` audits check exactly this. `actionlint` checks syntax,
+  expressions and embedded shell, not pinning. Do not assume CI runs either tool.
+- To make a workflow faster, use the `cratis-ci-pipeline-performance` skill.
 
 ## Matrices and operating systems
 

package/package/corpus/rules/profiles.md

@@ -86,11 +86,20 @@ profile includes neither Screenplay nor Stage.
 | Profile ID | Description | Automatically Includes |
 |---|---|---|
 | `cratis/engineering` | Engineering conventions and workflows | `cratis/engineering/core`, `cratis/engineering/csharp`, `cratis/engineering/elixir`, `cratis/engineering/go`, `cratis/engineering/kotlin`, `cratis/engineering/react`, `cratis/engineering/typescript` |
-| `cratis/engineering/csharp` | C# engineering conventions and framework Orleans jobs (`cratis-orleans-jobs`, alongside `orleans.md`) | `cratis/engineering/core` |
+| `cratis/engineering/csharp` | C# engineering conventions, .NET engineering skills, and framework Orleans jobs (`cratis-orleans-jobs`, alongside `orleans.md`) | `cratis/engineering/core`, `cratis/engineering/dotnet` |
+| `cratis/engineering/dotnet` | Upstream .NET engineering workflows | `cratis/engineering/dotnet/performance`, `cratis/engineering/dotnet/diagnostics`, `cratis/engineering/dotnet/msbuild`, `cratis/engineering/dotnet/orleans`, `cratis/engineering/dotnet/testing`, `cratis/engineering/dotnet/refactoring` |
+| `cratis/engineering/dotnet/performance` | Microbenchmarking, performance patterns, SIMD, and profiling | (no child profiles) |
+| `cratis/engineering/dotnet/diagnostics` | Trace and crash-dump collection | (no child profiles) |
+| `cratis/engineering/dotnet/msbuild` | MSBuild troubleshooting, build authoring, output paths, and binlogs | (no child profiles) |
+| `cratis/engineering/dotnet/orleans` | Orleans primitives, hosting, persistence, and runtime behavior | (no child profiles) |
+| `cratis/engineering/dotnet/testing` | Test-platform detection, runner commands, filters, and coverage | (no child profiles) |
+| `cratis/engineering/dotnet/refactoring` | Behavior-preserving C# refactoring and AOT compatibility | (no child profiles) |
 | `cratis/engineering/go` | Go framework parity and immutable module releases | `cratis/engineering/core`, `cratis/language/go` |
 | `cratis/engineering/typescript` | TypeScript engineering conventions | `cratis/engineering/core` |
 | `cratis/engineering/react` | React engineering conventions | `cratis/engineering/core` |
 
+The `cratis/engineering/dotnet` profiles carry upstream skills under MIT, with attribution and changes in each skill's NOTICE. Cratis rules and the `cratis-*` skills win where they differ.
+
 The `cratis/engineering` profile also carries [issue-assignment.md](./issue-assignment.md): when an agent starts work on a numbered issue in a known repository and nobody is assigned, it assigns the current `gh` user.
 
 ### Language Profiles

package/package/corpus/rules/pull-requests.md

@@ -8,6 +8,8 @@ applyTo: "**/*"
 
 **The PR description is published verbatim as the GitHub release. In repositories released by `cratis/release-action`, it also closes every issue written as `(#n)`; elsewhere, follow the repository's own release and issue-closing process.** Write the note the person upgrading should read, not a development write-up. The same contract applies to release notes typed into a manual workflow run or written straight into a release. Where it is installed, the `policy / verify` check enforces it on release-bound PRs into the default branch carrying `major`/`minor`/`patch` (it re-runs when the label is added); its release-note step warns on `no-release` and unlabelled PRs, which must still be written this way because any of them may become releasable. `release-action` does not run for a `no-release` PR, so `(#n)` closes nothing there. Editing the description re-runs the check. HTML comments are not shown on the release page and the check ignores them for headings, keywords and placeholders, and `release-action` removes them before publishing, so a `(#n)` only inside a comment closes nothing; the check fails it, so never put an issue reference in a comment. The template's own comment can stay: its `(#123)` examples are inline code, and the comment is not published.
 
+**A change to a hook script or its wiring (`.cratis/ai/hooks/**`) needs a release-note line that tells consumers to run `cratis ai update`; a hook fix does not reach a repository until they do.**
+
 ### Allowed shape
 
 - Follow the repository's pull request template (`.github/pull_request_template.md`) within this contract.

package/package/corpus/rules/secrets.md

@@ -20,6 +20,10 @@ Every line is tagged **[contract]** (binding) per the Three Levels of Authority
 - **[contract] Project the field you need and say which one:** `-o jsonpath='{.spec.containers[*].image}'`,
   `-o custom-columns=…`, `kubectl get … -o name`, status fields, `kubectl logs`, `docker inspect --format`.
   Read a `.env.example`, never the `.env`.
+- **[contract] The hook reads command text only.** It cannot see a command piped into a shell
+  (`… | sh`, `bash -c "$(…)"`), a recursive search with no named file (`grep -r PASSWORD .`), or a
+  value reached through a variable, alias or script. These stay your rule to keep; output redaction
+  is the only backstop.
 
 ## Values
 

package/package/corpus/skills/analyzing-dotnet-performance/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/analyzing-dotnet-performance/NOTICE

@@ -0,0 +1,36 @@
+.NET Performance Patterns
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-diag/skills/analyzing-dotnet-performance/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Replace "I/O" with "input/output" in the description to satisfy the neutral-voice rule.
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line.
+- 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.
+
+references/structural-patterns.md:
+- Qualify sealing advice to preserve published framework/library public API compatibility.
+
+references/async-patterns.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/collections-and-linq.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/critical-patterns.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/io-and-serialization.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+references/memory-and-strings.md:
+- Add or normalize the top Contents list from existing headings; preserve section content.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.

package/package/corpus/skills/analyzing-dotnet-performance/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: analyzing-dotnet-performance
+description: 'Scans .NET code for about 50 performance anti-patterns across async, memory, strings, collections, LINQ, regex, serialization, and input/output, with tiered severity. Use when analyzing .NET code for optimization opportunities, reviewing hot paths, or auditing allocation-heavy patterns. Not for measuring or profiling a running process (use profiling or microbenchmarking) or for SIMD work (use vectorization).'
+license: MIT
+---
+
+<!-- Modified by Cratis from dotnet's original (MIT): frontmatter, applicability, navigation and the changes listed in NOTICE. Upstream: https://github.com/dotnet/skills (plugins/dotnet-diag/skills/analyzing-dotnet-performance/SKILL.md; see NOTICE) -->
+
+# .NET Performance Patterns
+
+Cratis rules in `.cratis/ai/rules/` (including `csharp.md`, `specs.csharp.md`, and `orleans.md`) and the `cratis-*` skills win where they differ.
+
+Scan C#/.NET code for performance anti-patterns and produce prioritized findings with concrete fixes. Patterns sourced from the official .NET performance blog series, distilled to customer-actionable guidance.
+
+## When to Use
+
+- Reviewing C#/.NET code for performance optimization opportunities
+- Auditing hot paths for allocation-heavy or inefficient patterns
+- Systematic scan of a codebase for known anti-patterns before release
+- Second-opinion analysis after manual performance review
+
+## When Not to Use
+
+- **Algorithmic complexity analysis** — this skill targets API usage patterns, not algorithm design
+- **Code not on a hot path** with no performance requirements — avoid premature optimization
+
+## Inputs
+
+| Input | Required | Description |
+|-------|----------|-------------|
+| Source code | Yes | C# files, code blocks, or repository paths to scan |
+| Hot-path context | Recommended | Which code paths are performance-critical |
+| Target framework | Recommended | .NET version (some patterns require .NET 8+) |
+| Scan depth | Optional | `critical-only`, `standard` (default), or `comprehensive` |
+
+## Workflow
+
+### Step 1: Load Critical Reference
+
+Resolve bundled paths from the directory that contains this `SKILL.md`, not from the user's workspace. Load this reference file first:
+
+- `references/critical-patterns.md`
+
+If a direct read fails, list this skill's `references/` directory once and retry only when the listing shows the expected file. Do not use workspace file or text search to locate the skill installation.
+
+### Step 2: Detect Code Signals and Select Topic Recipes
+
+Scan the code for signals that indicate which pattern categories to check. Use the `## Detection` section from the critical reference when available and the inline recipes in Step 3 for initial signal detection.
+
+After detecting signals, load only the topic-specific references selected by scan depth:
+
+- `critical-only`: No additional references (use only `critical-patterns.md`)
+- `standard` (default): Load references matching detected signals from this list:
+  - `references/async-patterns.md` — async/Task/ValueTask signals
+  - `references/memory-and-strings.md` — Span/Memory/string allocation signals
+  - `references/regex-patterns.md` — Regex signals
+  - `references/collections-and-linq.md` — Dictionary/List/LINQ signals
+  - `references/io-and-serialization.md` — JsonSerializer/HttpClient/Stream signals
+  - `references/structural-patterns.md` — always loaded (unsealed classes checked regardless)
+- `comprehensive`: Load all six topic-specific references above
+
+For coverage reporting, the selected references are `references/critical-patterns.md` plus only the topic-specific references selected above. If any selected reference remains unavailable after retry, use the inline recipes in Step 3 for the missing coverage. Include `Reference coverage: reduced; unavailable: <paths>; used inline recipes for missing references.` in the final report, with `<paths>` replaced by the missing relative paths of the selected references only.
+
+Use the `## Detection` sections from loaded reference files and the inline recipes in Step 3 for categories whose reference files are unavailable.
+
+| Signal in Code | Topic |
+|----------------|-------|
+| `async`, `await`, `Task`, `ValueTask` | Async patterns |
+| `Span<`, `Memory<`, `stackalloc`, `ArrayPool`, `string.Substring`, `.Replace(`, `.ToLower()`, `+=` in loops, `params` | Memory & strings |
+| `Regex`, `[GeneratedRegex]`, `Regex.Match`, `RegexOptions.Compiled` | Regex patterns |
+| `Dictionary<`, `List<`, `.ToList()`, `.Where(`, `.Select(`, LINQ methods, `static readonly Dictionary<` | Collections & LINQ |
+| `JsonSerializer`, `HttpClient`, `Stream`, `FileStream` | I/O & serialization |
+
+Always check structural patterns (unsealed classes) regardless of signals.
+
+**Scan depth controls scope:**
+- `critical-only`: Only critical patterns (deadlocks, >10x regressions)
+- `standard` (default): Critical + detected topic patterns
+- `comprehensive`: All pattern categories
+
+### Step 3: Scan and Report
+
+**For files under 500 lines, read the entire file first** — you'll spot most patterns faster than running individual grep recipes. Use grep to confirm counts and catch patterns you might miss visually.
+
+For each relevant pattern category, run the detection recipes below. Report exact counts, not estimates.
+
+**Core scan recipes** (run these when reference files aren't available):
+```
+# Strings & memory
+grep -n '\.IndexOf(\"' FILE                    # Missing StringComparison
+grep -n '\.Substring(' FILE                    # Substring allocations
+grep -En '\.(StartsWith|EndsWith|Contains)\s*\(' FILE  # Missing StringComparison
+grep -n '\.ToLower()\|\.ToUpper()' FILE        # Culture-sensitive + allocation
+grep -n '\.Replace(' FILE                      # Chained Replace allocations
+grep -n 'params ' FILE                         # params array allocation
+
+# Collections & LINQ
+grep -n '\.Select\|\.Where\|\.OrderBy\|\.GroupBy' FILE  # LINQ on hot path
+grep -n '\.All\|\.Any' FILE                    # LINQ on string/char
+grep -n 'new Dictionary<\|new List<' FILE      # Per-call allocation
+grep -n 'static readonly Dictionary<' FILE     # FrozenDictionary candidate
+
+# Regex
+grep -n 'RegexOptions.Compiled' FILE           # Compiled regex budget
+grep -n 'new Regex(' FILE                      # Per-call regex
+grep -n 'GeneratedRegex' FILE                  # Positive: source-gen regex
+
+# Structural
+grep -n 'public class \|internal class ' FILE  # Unsealed classes
+grep -n 'sealed class' FILE                    # Already sealed
+grep -n ': IEquatable' FILE                    # Positive: struct equality
+```
+
+**Rules:**
+- Run every relevant recipe for the detected pattern categories
+- **Emit a scan execution checklist** before classifying findings — list each recipe and the hit count
+- A result of **0 hits** is valid and valuable (confirms good practice)
+- If reference files were loaded, also run their `## Detection` recipes
+
+**Verify-the-Inverse Rule:** For absence patterns, always count both sides and report the ratio (e.g., "N of M classes are sealed"). The ratio determines severity — 0/185 is systematic, 12/15 is a consistency fix.
+
+### Step 3b: Cross-File Consistency Check
+
+If an optimized pattern is found in one file, check whether sibling files (same directory, same interface, same base class) use the un-optimized equivalent. Flag as 🟡 Moderate with the optimized file as evidence.
+
+### Step 3c: Compound Allocation Check
+
+After running scan recipes, look for these multi-allocation patterns that single-line recipes miss:
+
+1. **Branched `.Replace()` chains:** Methods that call `.Replace()` across multiple `if/else` branches — report total allocation count across all branches, not just per-line.
+2. **Cross-method chaining:** When a public method delegates to another method that itself allocates intermediates (e.g., A calls B which does 3 regex replaces, then A calls C), report the total chain cost as one finding.
+3. **Compound `+=` with embedded allocating calls:** Lines like `result += $"...{Foo().ToLower()}"` are 2+ allocations (interpolation + ToLower + concatenation) — flag the compound cost, not just the `.ToLower()`.
+4. **`string.Format` specificity:** Distinguish resource-loaded format strings (not fixable) from compile-time literal format strings (fixable with interpolation). Enumerate the actionable sites.
+
+### Step 4: Classify and Prioritize Findings
+
+Assign each finding a severity:
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| 🔴 **Critical** | Deadlocks, crashes, security vulnerabilities, >10x regression | Must fix |
+| 🟡 **Moderate** | 2-10x improvement opportunity, best practice for hot paths | Should fix on hot paths |
+| ℹ️ **Info** | Pattern applies but code may not be on a hot path | Consider if profiling shows impact |
+
+**Prioritization rules:**
+1. If the user identified hot-path code, elevate all findings in that code to their maximum severity
+2. If hot-path context is unknown, report 🔴 Critical findings unconditionally; report 🟡 Moderate findings with a note: _"Impactful if this code is on a hot path"_
+3. Never suggest micro-optimizations on code that is clearly not performance-sensitive
+
+**Scale-based severity escalation:**
+When the same pattern appears across many instances, escalate severity:
+- 1-10 instances of the same anti-pattern → report at the pattern's base severity
+- 11-50 instances → escalate ℹ️ Info patterns to 🟡 Moderate
+- 50+ instances → escalate to 🟡 Moderate with elevated priority; flag as a codebase-wide systematic issue
+
+Always report exact counts (from scan recipes), not estimates or agent summaries.
+
+### Step 5: Generate Findings
+
+**Keep findings compact.** Each finding is one short block — not an essay. Group by severity (🔴 → 🟡 → ℹ️), not by file.
+
+Format per finding:
+
+```
+#### ID. Title (N instances)
+**Impact:** one-line impact statement
+**Files:** file1.cs:L1, file2.cs:L2, ... (list locations, don't build tables)
+**Fix:** one-line description of the change (e.g., "Add `StringComparison.Ordinal` parameter")
+**Caveat:** only if non-obvious (version requirement, correctness risk)
+```
+
+**Rules for compact output:**
+- **No ❌/✅ code blocks** for trivial fixes (adding a keyword, parameter, or type change). A one-line fix description suffices.
+- **Only include code blocks** for non-obvious transformations (e.g., replacing a LINQ chain with a foreach loop, or hoisting a closure).
+- **File locations as inline comma-separated list**, not a table. Use `File.cs:L42` format.
+- **No explanatory prose** beyond the Impact line — the severity icon already conveys urgency.
+- **Merge related findings** that share the same fix (e.g., all `.ToLower()` calls go in one finding, not split by file).
+- **Positive findings** in a bullet list, not a table. One line per pattern: `✅ Pattern — evidence`.
+
+End with a summary table and disclaimer:
+
+```markdown
+| Severity | Count | Top Issue |
+|----------|-------|-----------|
+| 🔴 Critical | N | ... |
+| 🟡 Moderate | N | ... |
+| ℹ️ Info | N | ... |
+
+> ⚠️ **Disclaimer:** These results are generated by an AI assistant and are non-deterministic. Findings may include false positives, miss real issues, or suggest changes that are incorrect for your specific context. Always verify recommendations with benchmarks and human review before applying changes to production code.
+```
+
+## Validation
+
+Before delivering results, verify:
+
+- [ ] All critical patterns were checked (from reference files or inline recipes)
+- [ ] Topic-specific recipes run only when matching signals detected
+- [ ] Each finding includes a concrete code fix
+- [ ] Scan execution checklist is complete (all recipes run)
+- [ ] Summary table included at end
+
+## Common Pitfalls
+
+| Pitfall | Correct Approach |
+|---------|-----------------|
+| Flagging every `Dictionary` as needing `FrozenDictionary` | Only flag if the dictionary is never mutated after construction |
+| Suggesting `Span<T>` in async methods | Use `Memory<T>` in async code; `Span<T>` only in sync hot paths |
+| Reporting LINQ outside hot paths | Only flag LINQ in identified hot paths or tight loops; LINQ is acceptable in code that runs infrequently. Since .NET 7, LINQ Min/Max/Sum/Average are vectorized — blanket bans on LINQ are misguided |
+| Suggesting `ConfigureAwait(false)` in app code | Only applicable in library code; not primarily a performance concern |
+| Recommending `ValueTask` everywhere | Only for hot paths with frequent synchronous completion |
+| Flagging `new HttpClient()` in DI services | Check if `IHttpClientFactory` is already in use |
+| Suggesting `[GeneratedRegex]` for dynamic patterns | Only flag when the pattern string is a compile-time literal |
+| Suggesting `CollectionsMarshal.AsSpan` broadly | Only for ultra-hot paths with benchmarked evidence; adds complexity and fragility |
+| Suggesting `unsafe` code for micro-optimizations | Avoid `unsafe` except where absolutely necessary — do not recommend it for micro-optimizations that don't matter. Safe alternatives like `Span<T>`, `stackalloc` in safe context, and `ArrayPool` cover the vast majority of performance needs |