@cratis/pi 7.103.1 → 7.103.3

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/scripting.instructions.md

@@ -0,0 +1,22 @@
+---
+applyTo: "**/*.sh,**/*.py,**/*.mjs,**/*.cjs,**/*.ps1,**/scripts/**,**/tools/**,**/.github/workflows/**,**/.cratis/ai/hooks/**"
+paths:
+  - "**/*.sh"
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.ps1"
+  - "**/scripts/**"
+  - "**/tools/**"
+  - "**/.github/workflows/**"
+  - "**/.cratis/ai/hooks/**"
+---
+<!-- cratis-ai: generated Copilot instructions. Do not edit; rules/ is the source. -->
+
+# Scripts and tooling
+
+- Write repository scripts, CI helpers and tooling in Node (`.mjs`, or `.ts` limited to erasable syntax: no enums, no parameter properties), using only `node:` built-ins (`fs.glob`, `util.parseArgs`, `fetch`, `node:test`). Node and the .NET SDK are the only runtimes every Cratis build machine and runner is guaranteed to have.
+- Use a C# file-based app (`dotnet run --file tool.cs`, `#:package` pinned) when the script needs .NET or Cratis libraries or shares types with the product. Do not use one in hooks or on per-call hot paths.
+- Hooks under `.cratis/ai/hooks` are POSIX sh compatible with bash 3.2, or Node. Read stdin with `IFS= read -r -d '' x || true`, never `$(</dev/stdin)`.
+- Do not add Python scripts or `python3` workflow steps to Cratis repositories unless the project itself is Python (for example the Chronicle Python client). Existing Python scripts are ported to Node opportunistically: when you substantially change one, port it in the same PR. There is no bulk port.
+- Agents: edit files with the edit/write tools, query JSON with `gh --jq`/`jq`, and use `node -e` or `node --input-type=module - <<'EOF'` for ad-hoc logic. Never `python3 -c`, and never rewrite files by script.

package/package/corpus/rules/general.md

@@ -149,11 +149,11 @@ A claim is only as good as the signal behind it — a build result, a test run,
 | Before any browser call: production permit, handoff, artifact paths, evidence | `browser.md` |
 | Whether you are allowed to do the thing you are able to do | `capability-is-not-authority.md` |
 | Before running a command that could print a credential, or when a secret value appears in output | `secrets.md` |
-| What must stop and ask a human | `capability-is-not-authority.md` (absent authority for a consequential effect: stop and ask) |
+| What must stop and ask a human | `capability-is-not-authority.md` |
 | What counts as evidence that something works | `verification-discipline.md` |
 | Before writing a session note, plan or handover: where they may live (`.ai-work/` only) | `local-work-artifacts.md` |
 | What may be written into the `.cratis/` folder (configuration and the corpus only, never deliverables) | `cratis-folder-is-configuration.md` |
-| Exit-code meaning, scripts and wrappers that lose a verdict | `exit-codes-and-wrappers.md` |
+| Exit-code meaning, scripts and wrappers that lose a verdict; which language a script uses | `exit-codes-and-wrappers.md`, `scripting.md` |
 | Writing a scan, allowlist, script or CI check, or a destructive pass, that cannot pass vacuously | `guards-and-fuses.md` |
 | How the shared corpus is installed, updated and rolled back | `ai-distribution.md` |
 | Code-level event modeling / schema migration / calling commands from code / paging / cross-cutting metadata / multi-tenancy | the matching skills |

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/scripting.md

@@ -0,0 +1,21 @@
+---
+applyTo: "**/*.sh,**/*.py,**/*.mjs,**/*.cjs,**/*.ps1,**/scripts/**,**/tools/**,**/.github/workflows/**,**/.cratis/ai/hooks/**"
+paths:
+  - "**/*.sh"
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.ps1"
+  - "**/scripts/**"
+  - "**/tools/**"
+  - "**/.github/workflows/**"
+  - "**/.cratis/ai/hooks/**"
+---
+
+# Scripts and tooling
+
+- Write repository scripts, CI helpers and tooling in Node (`.mjs`, or `.ts` limited to erasable syntax: no enums, no parameter properties), using only `node:` built-ins (`fs.glob`, `util.parseArgs`, `fetch`, `node:test`). Node and the .NET SDK are the only runtimes every Cratis build machine and runner is guaranteed to have.
+- Use a C# file-based app (`dotnet run --file tool.cs`, `#:package` pinned) when the script needs .NET or Cratis libraries or shares types with the product. Do not use one in hooks or on per-call hot paths.
+- Hooks under `.cratis/ai/hooks` are POSIX sh compatible with bash 3.2, or Node. Read stdin with `IFS= read -r -d '' x || true`, never `$(</dev/stdin)`.
+- Do not add Python scripts or `python3` workflow steps to Cratis repositories unless the project itself is Python (for example the Chronicle Python client). Existing Python scripts are ported to Node opportunistically: when you substantially change one, port it in the same PR. There is no bulk port.
+- Agents: edit files with the edit/write tools, query JSON with `gh --jq`/`jq`, and use `node -e` or `node --input-type=module - <<'EOF'` for ad-hoc logic. Never `python3 -c`, and never rewrite files by script.

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.1",
+  "version": "7.103.3",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [