@cratis/pi 7.103.2 → 7.103.4

package/package/corpus/harnesses/copilot/instructions/github-actions.instructions.md

@@ -19,8 +19,9 @@ paths:
   jobs on the Free plan, 5 for macOS). Every queued job competes with every repository.
 - **Public repositories** run free on hosted runners; **private repositories bill every
   minute** — Linux 1×, Windows 2×, macOS 10× — against a small monthly allowance.
-- The organization runs its own scale set (`cratis-arc`). Jobs there cost nothing and
-  do not touch the hosted pool.
+- The organization runs self-hosted scale sets on UpCloud (`cratis-arc` and
+  `cratis-arc-small`). They do not touch the hosted pool, but share infrastructure
+  capacity and cost across Cratis repositories.
 
 ## Scheduling
 
@@ -54,6 +55,9 @@ paths:
   `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.
+- Avoid duplicate `push` and `pull_request` verification for the same feature-branch
+  commit: use pull requests for branch verification and restrict push verification
+  to the default branch. Filter unrelated heavy jobs by changed paths.
 - **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`).
@@ -74,9 +78,26 @@ paths:
 
 ## Runners
 
-- Private-repository jobs belong on the organization scale set: `runs-on: cratis-arc`,
-  or a repository variable such as `${{ vars.<REPO>_RUNNER || 'ubuntu-latest' }}` so
-  routing changes without a code change.
+These are judgment-shaped routing and cache choices. Read the
+[Infrastructure runner guide](https://github.com/Cratis/Infrastructure/blob/main/Documentation/deployment/github-runners.md)
+for UpCloud runner resources, ceilings and storage; link it rather than copying
+capacity numbers into workflows or guidance.
+
+- Use GitHub-hosted runners for public repositories (free hosted execution) and jobs
+  needing Windows or macOS. Private Linux jobs use `cratis-arc` for builds, specs,
+  audits, deployments or Docker; `cratis-arc-small` is only for lightweight script/API
+  guards. The small set has no Docker: no container actions, services or Testcontainers.
+  A repository runner variable can make routing configurable.
+- Compare job memory and in-job parallelism with the documented limits before
+  increasing fan-out. Both sets share nodes; pod ceilings and node cold starts can
+  make extra jobs wait. Use the `cratis-ci-pipeline-performance` skill for sizing.
+- Runner pods are ephemeral: workspaces, Docker data and local package downloads do
+  not persist between jobs. Use the shared Cratis cache actions, `actions/cache` or
+  `setup-*` caching keyed on lockfiles; never assume a warm local package cache.
+- When testing locally packed `0.0.0-ci` packages, a restored global NuGet cache can
+  supply stale bytes for the same package ID/version. Use a unique version per run,
+  a per-run packages folder, or remove that package from the restored cache before
+  restoring consumers. See the skill's `references/caching.md`.
 - On self-hosted runners, `actions/setup-dotnet` cannot write `/usr/share/dotnet`.
   Set `DOTNET_INSTALL_DIR: ${{ runner.temp }}/dotnet` on the setup step.
 - **Never** route `pull_request`-triggered jobs of a *public* repository to self-hosted

package/package/corpus/harnesses/copilot/instructions/go.instructions.md

@@ -24,7 +24,9 @@ exact commands.
 
 - Read the `go` directive, build constraints and CI before choosing a feature.
   The minimum is not the newest locally installed compiler; a `toolchain`
-  preference does not replace minimum-version testing. Do not raise it incidentally.
+  preference does not replace minimum-version testing. Do not raise it incidentally
+  or rewrite unrelated code to modernize syntax. Verify unfamiliar APIs against the
+  documentation for that minimum, and keep experimental features opt-in.
 - Iterators require Go 1.23; `T.Context` and `B.Loop` require 1.24;
   stable `testing/synctest` and `WaitGroup.Go` require 1.25.
 - Prefer the standard library when it meets the contract. Review dependency
@@ -33,6 +35,10 @@ exact commands.
   including indirect minimum-version changes; keep sums consistent. A consumer
   must not need a developer's workspace or local replacement.
 - Never edit generated code; change its authoritative inputs and pinned generator.
+- Start with a small public package surface aligned with caller workflows; put
+  implementation-only packages in `internal/` and keep optional adapters apart from
+  core behavior. Do not mandate `pkg/`. Avoid package initialization that performs
+  I/O, starts goroutines or mutates globals.
 
 ## Names, public APIs and values
 
@@ -44,11 +50,23 @@ exact commands.
 - Document exported declarations with comments beginning with their names.
   Explain nil/zero semantics, concurrency, ownership, cancellation, error identities
   and cleanup. Add executable examples for important public workflows.
-- Make zero values useful where possible; reject invalid construction early.
-  Document option defaults, validation, ordering and duplicates.
+- Design exported APIs from realistic caller examples first and export only what
+  the library will support. Make zero values useful where possible; reject invalid
+  construction early. Use plain parameters or config structs for simple
+  configuration and functional options when extensibility outweighs the added
+  namespace; document option defaults, validation, ordering and duplicates.
+- Reuse standard interfaces such as `io.Reader` and `http.Handler`; prefer concrete
+  returns unless an abstraction is part of the API. Use pointer receivers for
+  mutation or values that must not be copied, and avoid public embedding that
+  promotes dependency methods. Mark retired API with a `Deprecated:` paragraph
+  naming the replacement.
 - Use named domain values instead of interchangeable primitives. Defined types
   do not inherit codec methods; explicitly forward text/JSON codecs and test wire
   formats. See `cratis-fundamentals-concept-go` when using Fundamentals.Go.
+- Specify `Close` ownership, repeated-close behavior and use after close, and
+  document concurrent-use guarantees for clients, handles and callbacks.
+- Use generics for meaningful type-safe reuse, not speculative abstraction; do not
+  replace domain types with `any` for plumbing convenience.
 - Document whether slices, maps, config and results are owned, copied or borrowed.
   Copying a slice/map header is not a detached copy. Do not copy a used mutex,
   wait group or atomic value, or expose pooled bytes after returning their buffer.
@@ -62,7 +80,9 @@ exact commands.
   return an `error` interface containing a typed nil.
 - Add useful operation context. Handle/log an error at one boundary rather than
   repeatedly logging and returning it. A partial or ambiguous write is not success
-  and must not trigger a blind retry.
+  and must not trigger a blind retry. Use sentinels for stable categories and typed
+  errors for structured details; translate dependency errors whose identity must
+  stay internal, and explain intentional suppression.
 - Put `context.Context` first for blocking/cancelable work and propagate it through
   RPCs, HTTP, storage and callbacks. Never escape caller cancellation by replacing
   it with `Background`. Do not retain request contexts in long-lived clients.
@@ -73,6 +93,9 @@ exact commands.
 
 ## Goroutines, streams and iterators
 
+- Prefer synchronous APIs and let callers place concurrency. A saturated
+  `errgroup.SetLimit` can block `Go`; use `errgroup` only when its cancellation
+  and error behavior fits.
 - Each goroutine needs an owner, termination condition and observable join path.
   Cancellation requests termination; it does not join workers.
 - Bound workers, queues, subscriptions, buffers and retries; define backpressure.
@@ -85,6 +108,8 @@ exact commands.
 - Preserve protocol metadata, tenancy, checkpoints and duplicate-delivery semantics.
   No generic retry or stream helper may promise exactly-once effects.
 - Validate remote TLS identities. Development exceptions must be explicit.
+  Bound untrusted payload sizes, fan-out and retained subscription state, and keep
+  long-lived subscription lifetimes apart from unary-call deadlines.
   Use cryptographic randomness for secrets, never `math/rand`.
 
 ## Specifications and checks
@@ -98,10 +123,23 @@ exact commands.
 - Cover error identity, nil/zero input, cancellation/deadlines, partial outcomes,
   early stream exit and resource ownership. Bound fuzz duration and preserve
   failing seeds. Use race checks where supported; race-free does not mean leak-free.
+- Add a regression test for each corrected behavior, including error and boundary
+  cases. Use `httptest` or `bufconn` plus real-transport tests where needed, and
+  protobuf-aware comparison for generated types.
+- Profile or benchmark a demonstrated problem before optimizing; add no pools,
+  caches or `unsafe` without measured justification.
 - Run the repository's build, tests, formatting, vet and pinned golangci-lint gates,
   with race and vulnerability scanning as separate checks. Respect the declared
   minimum without silent toolchain upgrades. Report absent tools honestly.
 
+## Compatibility and releases
+
+- Prefer additive change: exported signature changes break callers, and adding a
+  method to an exported interface breaks its external implementations. Check struct comparability, embedding, defaults, errors and wire shape;
+  API-diff tools aid but cannot prove behavioral compatibility.
+- Introduce `/v2` only with a migration and parallel-support plan. Never move a
+  published tag; issue a corrective release and retract when needed.
+
 ## Adaptation and attribution
 
 This condensed rule adapts the repository-owned Go baseline at

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

@@ -18,8 +18,9 @@ paths:
   jobs on the Free plan, 5 for macOS). Every queued job competes with every repository.
 - **Public repositories** run free on hosted runners; **private repositories bill every
   minute** — Linux 1×, Windows 2×, macOS 10× — against a small monthly allowance.
-- The organization runs its own scale set (`cratis-arc`). Jobs there cost nothing and
-  do not touch the hosted pool.
+- The organization runs self-hosted scale sets on UpCloud (`cratis-arc` and
+  `cratis-arc-small`). They do not touch the hosted pool, but share infrastructure
+  capacity and cost across Cratis repositories.
 
 ## Scheduling
 
@@ -53,6 +54,9 @@ paths:
   `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.
+- Avoid duplicate `push` and `pull_request` verification for the same feature-branch
+  commit: use pull requests for branch verification and restrict push verification
+  to the default branch. Filter unrelated heavy jobs by changed paths.
 - **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`).
@@ -73,9 +77,26 @@ paths:
 
 ## Runners
 
-- Private-repository jobs belong on the organization scale set: `runs-on: cratis-arc`,
-  or a repository variable such as `${{ vars.<REPO>_RUNNER || 'ubuntu-latest' }}` so
-  routing changes without a code change.
+These are judgment-shaped routing and cache choices. Read the
+[Infrastructure runner guide](https://github.com/Cratis/Infrastructure/blob/main/Documentation/deployment/github-runners.md)
+for UpCloud runner resources, ceilings and storage; link it rather than copying
+capacity numbers into workflows or guidance.
+
+- Use GitHub-hosted runners for public repositories (free hosted execution) and jobs
+  needing Windows or macOS. Private Linux jobs use `cratis-arc` for builds, specs,
+  audits, deployments or Docker; `cratis-arc-small` is only for lightweight script/API
+  guards. The small set has no Docker: no container actions, services or Testcontainers.
+  A repository runner variable can make routing configurable.
+- Compare job memory and in-job parallelism with the documented limits before
+  increasing fan-out. Both sets share nodes; pod ceilings and node cold starts can
+  make extra jobs wait. Use the `cratis-ci-pipeline-performance` skill for sizing.
+- Runner pods are ephemeral: workspaces, Docker data and local package downloads do
+  not persist between jobs. Use the shared Cratis cache actions, `actions/cache` or
+  `setup-*` caching keyed on lockfiles; never assume a warm local package cache.
+- When testing locally packed `0.0.0-ci` packages, a restored global NuGet cache can
+  supply stale bytes for the same package ID/version. Use a unique version per run,
+  a per-run packages folder, or remove that package from the restored cache before
+  restoring consumers. See the skill's `references/caching.md`.
 - On self-hosted runners, `actions/setup-dotnet` cannot write `/usr/share/dotnet`.
   Set `DOTNET_INSTALL_DIR: ${{ runner.temp }}/dotnet` on the setup step.
 - **Never** route `pull_request`-triggered jobs of a *public* repository to self-hosted

package/package/corpus/rules/go.md

@@ -23,7 +23,9 @@ exact commands.
 
 - Read the `go` directive, build constraints and CI before choosing a feature.
   The minimum is not the newest locally installed compiler; a `toolchain`
-  preference does not replace minimum-version testing. Do not raise it incidentally.
+  preference does not replace minimum-version testing. Do not raise it incidentally
+  or rewrite unrelated code to modernize syntax. Verify unfamiliar APIs against the
+  documentation for that minimum, and keep experimental features opt-in.
 - Iterators require Go 1.23; `T.Context` and `B.Loop` require 1.24;
   stable `testing/synctest` and `WaitGroup.Go` require 1.25.
 - Prefer the standard library when it meets the contract. Review dependency
@@ -32,6 +34,10 @@ exact commands.
   including indirect minimum-version changes; keep sums consistent. A consumer
   must not need a developer's workspace or local replacement.
 - Never edit generated code; change its authoritative inputs and pinned generator.
+- Start with a small public package surface aligned with caller workflows; put
+  implementation-only packages in `internal/` and keep optional adapters apart from
+  core behavior. Do not mandate `pkg/`. Avoid package initialization that performs
+  I/O, starts goroutines or mutates globals.
 
 ## Names, public APIs and values
 
@@ -43,11 +49,23 @@ exact commands.
 - Document exported declarations with comments beginning with their names.
   Explain nil/zero semantics, concurrency, ownership, cancellation, error identities
   and cleanup. Add executable examples for important public workflows.
-- Make zero values useful where possible; reject invalid construction early.
-  Document option defaults, validation, ordering and duplicates.
+- Design exported APIs from realistic caller examples first and export only what
+  the library will support. Make zero values useful where possible; reject invalid
+  construction early. Use plain parameters or config structs for simple
+  configuration and functional options when extensibility outweighs the added
+  namespace; document option defaults, validation, ordering and duplicates.
+- Reuse standard interfaces such as `io.Reader` and `http.Handler`; prefer concrete
+  returns unless an abstraction is part of the API. Use pointer receivers for
+  mutation or values that must not be copied, and avoid public embedding that
+  promotes dependency methods. Mark retired API with a `Deprecated:` paragraph
+  naming the replacement.
 - Use named domain values instead of interchangeable primitives. Defined types
   do not inherit codec methods; explicitly forward text/JSON codecs and test wire
   formats. See `cratis-fundamentals-concept-go` when using Fundamentals.Go.
+- Specify `Close` ownership, repeated-close behavior and use after close, and
+  document concurrent-use guarantees for clients, handles and callbacks.
+- Use generics for meaningful type-safe reuse, not speculative abstraction; do not
+  replace domain types with `any` for plumbing convenience.
 - Document whether slices, maps, config and results are owned, copied or borrowed.
   Copying a slice/map header is not a detached copy. Do not copy a used mutex,
   wait group or atomic value, or expose pooled bytes after returning their buffer.
@@ -61,7 +79,9 @@ exact commands.
   return an `error` interface containing a typed nil.
 - Add useful operation context. Handle/log an error at one boundary rather than
   repeatedly logging and returning it. A partial or ambiguous write is not success
-  and must not trigger a blind retry.
+  and must not trigger a blind retry. Use sentinels for stable categories and typed
+  errors for structured details; translate dependency errors whose identity must
+  stay internal, and explain intentional suppression.
 - Put `context.Context` first for blocking/cancelable work and propagate it through
   RPCs, HTTP, storage and callbacks. Never escape caller cancellation by replacing
   it with `Background`. Do not retain request contexts in long-lived clients.
@@ -72,6 +92,9 @@ exact commands.
 
 ## Goroutines, streams and iterators
 
+- Prefer synchronous APIs and let callers place concurrency. A saturated
+  `errgroup.SetLimit` can block `Go`; use `errgroup` only when its cancellation
+  and error behavior fits.
 - Each goroutine needs an owner, termination condition and observable join path.
   Cancellation requests termination; it does not join workers.
 - Bound workers, queues, subscriptions, buffers and retries; define backpressure.
@@ -84,6 +107,8 @@ exact commands.
 - Preserve protocol metadata, tenancy, checkpoints and duplicate-delivery semantics.
   No generic retry or stream helper may promise exactly-once effects.
 - Validate remote TLS identities. Development exceptions must be explicit.
+  Bound untrusted payload sizes, fan-out and retained subscription state, and keep
+  long-lived subscription lifetimes apart from unary-call deadlines.
   Use cryptographic randomness for secrets, never `math/rand`.
 
 ## Specifications and checks
@@ -97,10 +122,23 @@ exact commands.
 - Cover error identity, nil/zero input, cancellation/deadlines, partial outcomes,
   early stream exit and resource ownership. Bound fuzz duration and preserve
   failing seeds. Use race checks where supported; race-free does not mean leak-free.
+- Add a regression test for each corrected behavior, including error and boundary
+  cases. Use `httptest` or `bufconn` plus real-transport tests where needed, and
+  protobuf-aware comparison for generated types.
+- Profile or benchmark a demonstrated problem before optimizing; add no pools,
+  caches or `unsafe` without measured justification.
 - Run the repository's build, tests, formatting, vet and pinned golangci-lint gates,
   with race and vulnerability scanning as separate checks. Respect the declared
   minimum without silent toolchain upgrades. Report absent tools honestly.
 
+## Compatibility and releases
+
+- Prefer additive change: exported signature changes break callers, and adding a
+  method to an exported interface breaks its external implementations. Check struct comparability, embedding, defaults, errors and wire shape;
+  API-diff tools aid but cannot prove behavioral compatibility.
+- Introduce `/v2` only with a migration and parallel-support plan. Never move a
+  published tag; issue a corrective release and retract when needed.
+
 ## Adaptation and attribution
 
 This condensed rule adapts the repository-owned Go baseline at

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

@@ -111,11 +111,12 @@ when keyed on `github.ref` for merged `pull_request` `closed` events). A workflo
 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.
+**Runner routing.** Fits queue-bound workflows. Read the
+[Infrastructure runner guide](https://github.com/Cratis/Infrastructure/blob/main/Documentation/deployment/github-runners.md)
+for the UpCloud scale sets `cratis-arc` and `cratis-arc-small`; do not copy its
+capacity numbers. The rule owns routing and public-fork safety. Read
+`references/runner-sizing-and-images.md` when choosing hosted versus self-hosted
+runners, sizing in-job parallelism or weighing fan-out against cold starts.
 
 **Publish from tested artifacts.** Fits release workflows that rebuild what the
 pull-request run already built and tested. Default: build and pack once, then
@@ -195,7 +196,7 @@ touches `permissions:`, uses `pull_request_target`, or adds a cache.
 - 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/runner-sizing-and-images.md` when choosing runners, sizing parallelism, or 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.

package/package/corpus/skills/cratis-ci-pipeline-performance/references/caching.md

@@ -1,16 +1,18 @@
 # Caching
 
-Use this when a job spends measurable time restoring packages, installing a
-frontend toolchain or rebuilding Docker layers. Check the slowest-steps table
-first: a step under a minute is not worth a cache.
-
 ## Contents
 
 - Shared Cratis cache actions
+- Ephemeral runner pods
 - NuGet and Yarn determinism
+- Locally packed CI packages
 - Docker layer cache
 - Scope, eviction and safety
 
+Use this when a job spends measurable time restoring packages, installing a
+frontend toolchain or rebuilding Docker layers. Check the slowest-steps table
+first: a step under a minute is not worth a cache.
+
 ## Shared Cratis cache actions
 
 The `Cratis/Workflows` repository ships two composite actions. Use them instead
@@ -35,6 +37,17 @@ key and one path list.
   workflow on that branch never warms one. Add a scheduled warm-up workflow that
   runs the same restore and build.
 
+## Ephemeral runner pods
+
+Cratis self-hosted runners use per-job pods: workspace files, package downloads
+and Docker data disappear with the job. A warm runner or node image does not make
+`~/.nuget/packages`, the Yarn/npm download cache or BuildKit layers persistent.
+Use the shared actions above, or explicit `actions/cache` / `setup-*` dependency
+caching when the shared actions do not fit. Key downloads on the OS, toolchain and
+committed lockfiles (`packages.lock.json`, `yarn.lock` or `package-lock.json`),
+and use remote Docker layer caching below. Do not cache `node_modules` as a
+substitute for an immutable install.
+
 ## NuGet and Yarn determinism
 
 A cache is only as stable as its key. Make the key inputs deterministic.
@@ -48,6 +61,34 @@ A cache is only as stable as its key. Make the key inputs deterministic.
   caches across commits are rarely correct; share build output within a run as an
   artifact instead (see `build-once-and-shard.md`).
 
+## Locally packed CI packages
+
+A repository that packs `0.0.0-ci` repeatedly and tests a consumer can restore an
+older package with the same ID/version from cached `~/.nuget/packages`. NuGet can
+reuse the extracted package without reading the newly packed bytes, so a green
+consumer test may exercise the wrong code. A lockfile cache key alone does not
+fix an unchanged local package version.
+
+Default: pack a unique prerelease version per run and attempt, and make the
+consumer reference that exact version. If the version must stay fixed, set a
+per-run packages folder for **every restore/build/test that can restore** in both
+the producer and consumer, and do not restore the global package cache into it:
+
+```yaml
+env:
+  NUGET_PACKAGES: ${{ runner.temp }}/nuget-${{ github.run_id }}-${{ github.run_attempt }}
+```
+
+Alternatively, after cache restoration and before consumer restore, remove only
+the locally packed package's ID/version directory from the global packages
+folder. Keep unrelated dependency downloads cached. A fresh runner is not enough
+if the workflow restores stale package bytes from a remote cache.
+
+Verify with `dotnet restore <consumer.csproj> --verbosity normal` followed by the
+consumer's focused test command. Pass means restore resolves the newly packed
+ID/version from the intended feed/folder and the test exercises behavior added
+in that package, not merely that a cached restore succeeds.
+
 ## Docker layer cache
 
 ```yaml

package/package/corpus/skills/cratis-ci-pipeline-performance/references/required-checks-and-path-filters.md

@@ -4,6 +4,7 @@
 
 - The hang
 - Change detection and the aggregator
+- Avoiding redundant runs
 - Keeping required checks stable
 - Merge queue
 
@@ -82,6 +83,35 @@ jobs:
   build). For one event, `paths` and `paths-ignore` cannot be combined; use
   `paths` with `!` negation patterns.
 
+## Avoiding redundant runs
+
+On the shared Cratis runner pools, two events for the same feature-branch commit
+consume capacity that another repository needs. Verify open pull requests through
+`pull_request` and restrict push verification to the default branch:
+
+```yaml
+on:
+  pull_request:
+  push:
+    branches: [main]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+```
+
+Use the repository's actual default branch. Keep publish/release/deploy workflows
+separate and follow their non-cancelling queue rules in
+[github-actions.md](../../../rules/github-actions.md). Cancellation stops obsolete
+PR runs; it does not deduplicate `push` and `pull_request` events, whose refs differ.
+Use change detection above to avoid unrelated heavy jobs without suppressing the
+required aggregator. Retain any required `merge_group` trigger as described below.
+
+Verify event deduplication with
+`gh run list --workflow <workflow.yml> --commit <sha> --json event,headSha,status`:
+a PR update should have one verification run for that workflow, not both a push
+and a pull-request run. Check that a superseded PR run cancels, unrelated paths
+skip heavy jobs, and the required aggregator still reports.
+
 ## Keeping required checks stable
 
 Branch protection matches check names. Renaming a job, changing a matrix key or

package/package/corpus/skills/cratis-ci-pipeline-performance/references/runner-sizing-and-images.md

@@ -1,16 +1,55 @@
 # Runner sizing, images and cache layers
 
-Use this when every job is uniformly slow, when jobs spend time pulling or
-installing tools, or when deciding how to warm workspaces.
-
 ## Contents
 
+- Choosing Cratis runners
 - Cores per job before job count
 - Container images
 - Tools baked into the runner image
 - Cache layers and warm workspaces
 - Publish stages
 
+Use this when every job is uniformly slow, when jobs spend time pulling or
+installing tools, or when choosing runners and deciding how to warm workspaces.
+
+## Choosing Cratis runners
+
+Read the [Infrastructure runner guide](https://github.com/Cratis/Infrastructure/blob/main/Documentation/deployment/github-runners.md)
+for the UpCloud scale sets, resource requests and limits, pod ceilings, scratch
+storage and autoscaling. Keep those numbers there, not in this skill. The routing
+and public-fork safety invariants live in
+[github-actions.md](../../../rules/github-actions.md).
+
+Choose by the work, not just the queue length:
+
+| Choice | When it fits | Check before routing |
+|---|---|---|
+| GitHub-hosted | Public repositories, Windows/macOS jobs | Public hosted execution is free; compare queue and startup time, not just billed minutes |
+| `cratis-arc-small` | Lightweight script/API guards such as release-note or work-record checks | No Docker daemon, container actions, service containers or Testcontainers; not for builds, specs, audits or deployments |
+| `cratis-arc` | Private Linux builds, specs, dependency audits, deployments and Docker work | Fit peak memory, worker count and scratch use inside the documented limits |
+
+For example, a private-repository release-note script can use
+`runs-on: cratis-arc-small`; a private-repository Testcontainers suite needs
+`runs-on: cratis-arc`.
+
+- Measure peak memory for the whole job, including Docker services and test
+  workers. Leave headroom below the documented limit; an OOM is not evidence that
+  more shards will help when those shards share nodes.
+- Set build/test worker counts from the pod's CPU and memory limits, not the
+  node's advertised cores. A larger in-job worker count can cause contention.
+- Compare fan-out with each set's pod ceiling and the shared node pool. More
+  shards can wait for slots or node autoscaling instead of shortening the run.
+- Include runner startup, image pulls and fresh-node provisioning in wall time.
+  For short jobs, merge compatible checks with one setup before adding shards;
+  compare the hosted alternative where routing policy permits it.
+- Reduce redundant work before requesting capacity: apply PR cancellation,
+  change-detected heavy jobs and event deduplication as described in
+  `required-checks-and-path-filters.md` and the owning rule.
+
+Do not infer live node counts, runner cost/quotas, network/egress policy or shared
+package-cache availability from the YAML. Record missing operational facts in
+Infrastructure, not as assumptions in the corpus.
+
 ## Cores per job before job count
 
 Undersized runner pods (a small CPU request or limit) make every job slow, and more
@@ -45,6 +84,12 @@ a version check. Keep the image's contents versioned so a change is reviewable.
 Prefer content-addressed caches, which are correct by construction, before
 warm volumes:
 
+Cratis runner pods start with per-job workspaces and Docker storage; neither is
+a persistent shared NuGet, npm or BuildKit cache. Restore remote caches explicitly
+(see `caching.md`) rather than treating a previous job's downloads as available.
+The layers below are options to configure, not claims that Infrastructure provides
+them:
+
 1. A registry mirror or pull-through cache for images.
 2. A remote or registry-backed BuildKit cache (see `caching.md`).
 3. Package caches keyed by lock files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.103.2",
+  "version": "7.103.4",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [