@cratis/pi 7.101.0 → 7.103.0

package/package/corpus/skills/cratis-ci-pipeline-performance/references/build-once-and-shard.md

@@ -0,0 +1,158 @@
+# Build once, shard the tests
+
+## Contents
+
+- When it fits
+- Shape
+- Decisions
+- Pitfalls
+- Fewer, bigger jobs
+
+Use this when one workflow builds the same code more than once, or runs build and
+tests serially in one long job. The pattern: a single build job compiles in
+`Release` and uploads the output; a shard matrix downloads it and runs the tests
+with `--no-build`. The wall clock becomes build + the slowest shard instead of
+build + all tests.
+
+## When it fits
+
+- The report shows `execution-bound` and one job holds most of the span.
+- Several jobs each restore and compile the same solution.
+- Tests are independent by project or namespace.
+
+It does not fit when the build is short compared with job start cost, or when
+the report is `queue-bound`: more shards are more independently scheduled jobs.
+Merge shards first, then re-measure.
+
+## Shape
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7 # pin by full commit SHA
+      - uses: actions/setup-dotnet@v6 # pin by full commit SHA
+      - uses: Cratis/Workflows/.github/actions/dotnet-cache@main
+      - run: dotnet build Repo.slnx --configuration Release
+      - name: Archive build output
+        run: |
+          set -euo pipefail
+          find . -type d -name bin -not -path '*/node_modules/*' -not -path './.git/*' -print0 \
+            | tar --null -T - --zstd -cf build-output.tar.zst
+      - uses: actions/upload-artifact@v7 # pin by full commit SHA
+        with:
+          name: build-output
+          path: build-output.tar.zst
+          compression-level: 0
+          retention-days: 1
+          if-no-files-found: error
+
+  specs:
+    name: ${{ matrix.shard }}
+    needs: [build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - shard: specs-1
+            projects: Source/Core.Specs Source/Storage.Specs
+          - shard: specs-2
+            projects: Source/Api.Specs
+          - shard: specs-3
+            projects: Source/Client.Specs Source/Tools.Specs
+    steps:
+      - uses: actions/checkout@v7 # pin by full commit SHA
+      - uses: actions/setup-dotnet@v6 # pin by full commit SHA
+      - uses: actions/download-artifact@v8 # pin by full commit SHA
+        with:
+          name: build-output
+      - run: tar --zstd -xf build-output.tar.zst
+      - name: Test the shard's projects
+        env:
+          PROJECTS: ${{ matrix.projects }}
+        run: |
+          failed=0
+          for project in $PROJECTS; do
+            dotnet test "$project" --no-build --configuration Release \
+              --logger "trx;LogFileName=$(basename "$project").trx" \
+              --results-directory "$RUNNER_TEMP/test-results" || failed=1
+          done
+          exit "$failed"
+      - name: Verify every project ran tests
+        if: ${{ !cancelled() }}
+        env:
+          PROJECTS: ${{ matrix.projects }}
+        run: |
+          failed=0
+          for project in $PROJECTS; do
+            file="$RUNNER_TEMP/test-results/$(basename "$project").trx"
+            executed=$(grep -o -m1 'executed="[0-9]*"' "$file" 2>/dev/null | grep -o '[0-9]*' || echo 0)
+            echo "$project executed $executed tests"
+            [ "$executed" -gt 0 ] || failed=1
+          done
+          exit "$failed"
+      - uses: actions/upload-artifact@v7 # pin by full commit SHA
+        if: ${{ !cancelled() }}
+        with:
+          name: test-results-${{ matrix.shard }}
+          path: ${{ runner.temp }}/test-results/*.trx
+          if-no-files-found: warn
+```
+
+Each matrix entry carries its own `projects` list, which the test step reads, so
+shards run different tests. For a test framework filter instead of a project list,
+carry the filter in the entry (`filter: FullyQualifiedName~Core`) and pass it as
+`--filter`. Keep the assignment in the workflow or one checked-in script so that
+adding a project cannot leave it unassigned; review the list when a project is added.
+
+To balance, read each shard job's median duration from the slowest-jobs table of
+`ci-timings.sh`, move a project from the longest shard to the shortest, and
+re-measure; stop when the spread is within the job start cost.
+
+## Decisions
+
+- **Artifact, not cache, between jobs of one run.** A cache keyed on the commit
+  SHA is immutable: one failed save poisons the key for every later attempt and a
+  rerun cannot recover. An artifact belongs to the run and is the intended
+  primitive for passing build output between its jobs.
+- **Archive with `tar`.** Artifact upload does not preserve file permissions or
+  empty directories; a tar keeps both. Output that was already compressed should
+  not be compressed again: `compression-level: 0`.
+- **Include every consumed output.** Frontend-dependent specs need the built
+  `dist` folders as well as `bin`; list them in the archive.
+- **Short retention.** `retention-days: 1` for build output nobody downloads by
+  hand. Test results can live longer.
+- **Same configuration end to end.** Test with the configuration that built
+  (`--configuration Release --no-build`); a different one silently rebuilds.
+- **`fail-fast: false`** on shard matrices, so one failing shard does not hide the
+  results of the others, and a rerun of failed jobs reruns only the failed shard.
+- **Upload results with `if: ${{ !cancelled() }}`** so failures keep their TRX.
+
+## Pitfalls
+
+- A filter or project list that matches nothing passes `dotnet test`. End every
+  shard with a check that each assigned project or namespace ran at least one test,
+  and print the counts. Zero tests is a failed shard.
+- Shards balance by test time, not by project count (see the balancing steps
+  after the example).
+- A shard that downloads a large artifact pays that transfer on every job; measure
+  the download step in the slowest-steps table before adding shards.
+- Static assets outside `bin`/`dist` (generated sources, local tool caches) must
+  be in the archive or regenerated by the shard.
+
+## Fewer, bigger jobs
+
+When the report is `queue-bound`, every extra job costs a scheduler start, a
+checkout and a toolchain setup. Merge sibling jobs that share setup (several
+lint or format checks, several small build legs) into one job with several steps.
+Keep a job separate only when it is on the critical path and long enough that
+parallelism repays its start. State the expected effect on both wall clock and
+runner-minutes, since merging parallel work lengthens the chain.

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

@@ -0,0 +1,86 @@
+# 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
+- NuGet and Yarn determinism
+- Docker layer cache
+- Scope, eviction and safety
+
+## Shared Cratis cache actions
+
+The `Cratis/Workflows` repository ships two composite actions. Use them instead
+of hand-written `actions/cache` steps so every workflow of a repository uses one
+key and one path list.
+
+```yaml
+- uses: Cratis/Workflows/.github/actions/dotnet-cache@main
+- uses: Cratis/Workflows/.github/actions/yarn-cache@main
+  with:
+    working-directory: Source/JavaScript
+```
+
+- `mode` is `auto` by default: pull requests only restore; a push to the default
+  branch, a schedule or a manual run on the default branch saves. Use `restore`
+  to never save and `save` to always save.
+- `dotnet-cache` inputs: `path`, `key-files`, `key-prefix`, `mode`. Keep `path`
+  identical everywhere; a different path list is a different cache. Bump the
+  version suffix of `key-prefix` to start a fresh cache.
+- Outputs: `cache-hit`, `matched-key`, `key`, `mode`.
+- A cache is only saved from the default branch, so a repository with no push
+  workflow on that branch never warms one. Add a scheduled warm-up workflow that
+  runs the same restore and build.
+
+## NuGet and Yarn determinism
+
+A cache is only as stable as its key. Make the key inputs deterministic.
+
+- NuGet: enable lock files (`<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>`)
+  and restore with `dotnet restore --locked-mode` in CI, so the lock file hash
+  keys the cache and a drifting dependency fails loudly.
+- Yarn: commit `yarn.lock` and install with `yarn install --immutable`; the
+  install fails instead of rewriting the lock file.
+- Cache the package download directories, not `bin`/`obj` output. Build output
+  caches across commits are rarely correct; share build output within a run as an
+  artifact instead (see `build-once-and-shard.md`).
+
+## Docker layer cache
+
+```yaml
+- uses: docker/setup-buildx-action@v4 # pin by full commit SHA
+- uses: docker/build-push-action@v7 # pin by full commit SHA
+  with:
+    context: .
+    push: false
+    cache-from: type=gha,scope=api-linux-amd64
+    cache-to: type=gha,scope=api-linux-amd64,mode=max
+```
+
+- Set a custom `scope` per image and platform. The default scope is shared, so
+  two builds overwrite each other's cache and both see misses.
+- `mode=max` caches intermediate layers of multi-stage builds; the default caches
+  only the final image layers.
+- Order the Dockerfile so rarely changing layers (base image, dependency
+  restore) come before source copies.
+- When an image is built once and pulled by several jobs, pushing it to a
+  registry and pulling it costs a transfer per job; measure that pull in the
+  slowest-steps table against rebuilding from cache.
+
+## Scope, eviction and safety
+
+- A pull request run can read caches of its own ref and of the base branch; a
+  cache saved on the default branch is readable by every branch. A cache saved by
+  one pull request is not visible to others.
+- Repository cache storage is bounded (10 GB by default). When full, or after a
+  week without access, entries are evicted, least recently used first. A large
+  rarely used cache can evict a hot one.
+- Caches must not contain secrets, tokens or credentials: restored content is
+  executed and readable by later runs of the same scope.
+- Never restore a cache written by an untrusted pull request into a privileged
+  workflow. See `security-and-pinning.md`.
+- Verify a cache works by reading the `cache-hit` output (or the restore step
+  log) on a second run, then re-measure with `ci-timings.sh`.

package/package/corpus/skills/cratis-ci-pipeline-performance/references/flaky-and-hung-jobs.md

@@ -0,0 +1,70 @@
+# Flaky and hung jobs
+
+Use this when the report is `failure-bound` (failed or rerun at or above the
+hint threshold) or a job occasionally runs to its timeout. Reruns and failures
+cost runner-minutes and developer trust; diagnose before retrying.
+
+## Diagnose
+
+1. Run `ci-timings.sh` with `--branch main` and again with `--event pull_request`.
+   Failures on the default branch with no code change are flakes or environment
+   problems; failures only on pull requests are mostly real.
+2. Group the failing runs by job and step name. One step that fails across many
+   runs is a defect in that step, not noise.
+3. Separate the cause: a hung test, a timeout from an external service, an
+   out-of-memory kill, or an infrastructure cancellation.
+
+## Bound every job
+
+- `timeout-minutes` on every job, per the rule. A hung job otherwise holds a
+  runner slot for up to six hours.
+- Set the job timeout above the test timeout, so dump collection and cleanup have
+  time to finish.
+
+## Find hangs and crashes in .NET
+
+```bash
+dotnet test Repo.slnx --configuration Release --no-build \
+  --blame-hang --blame-hang-timeout 5m --blame-crash \
+  --results-directory TestResults
+```
+
+- This is the VSTest form. Microsoft.Testing.Platform projects use their own
+  crash and hang dump extensions and options; do not mix the two sets of switches.
+- Upload `TestResults` as an artifact with `if: ${{ !cancelled() }}`, so the dump
+  survives the failure.
+
+## Retry only a diagnosed flake
+
+- Retry the smallest unit: a single test or a single failed job, never the whole
+  suite. With Microsoft.Testing.Platform, the retry extension provides
+  `--retry-failed-tests` with a failure-percentage ceiling; plain VSTest has no
+  equivalent flag.
+- Keep the first-attempt failure visible. A retry that turns red green without a
+  record hides the flake and doubles minutes.
+- Retrying a deterministic failure only consumes capacity.
+
+## Quarantine
+
+A quarantined test is a decision with an owner, not a deletion:
+
+- Mark it with the framework's skip or category mechanism and a reason that names
+  an issue.
+- Run quarantined tests in a separate, visible, non-required lane so they keep
+  producing signal.
+- Give the issue an owner and an expiry; an entry nobody revisits is a check
+  quietly deleted.
+
+## Fail fast
+
+Put the cheap, high-signal gates (format, lint, unit-level tests) before the
+expensive legs and make the expensive legs `needs` them. A failure then costs
+minutes instead of the full pipeline. Keep the gate short: a slow gate on the
+critical path moves the cost instead of removing it.
+
+## Cancelled work
+
+A high cancelled share is expected on pull requests with `cancel-in-progress`.
+It is waste only when the cancelled runs had already spent their expensive legs.
+Reduce it by ordering cheap legs first and by keeping the full matrix off the
+pull-request path, not by removing the cancellation.

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

@@ -0,0 +1,67 @@
+# Publish and release pipelines
+
+Use this when a release, package-publish or deploy workflow queues, loses runs,
+or rebuilds what a pull-request run already built and tested. Release method and
+assurance tiers belong to `cratis-governed-release-methodology`.
+
+## Concurrency for publishing
+
+```yaml
+concurrency:
+  group: publish-${{ github.repository }}
+  cancel-in-progress: false
+  queue: max
+```
+
+- Pull-request verification cancels superseded runs. Publish never does: a
+  cancelled half-publish is worse than a queued one.
+- A concurrency group holds one running and, by default, one pending run; a newer
+  arrival replaces the pending one. `queue: max` keeps up to 100 pending runs in
+  the group and processes them in order. It is valid only while
+  `cancel-in-progress` is `false` or unset; never combine it with `true`.
+- Replacement only happens between runs of the same group, so read the group key.
+  Merges into the default branch share one group: a push, a repository-wide key, or
+  `github.ref` on a merged `pull_request` `closed` event, where `github.ref` is the
+  base branch (for example `refs/heads/main`). A newer merge's pending run then
+  replaces the older pending one unless `queue: max` is set. Only a `closed` event
+  of an unmerged pull request keeps `refs/pull/N/merge`, a group of its own.
+- A replaced pending run is lost work only when that run alone would have released
+  something. Release tooling that aggregates everything since the last release
+  loses nothing when a pending run is replaced; such a workflow may keep one
+  pending slot, with a comment beside the `concurrency` block saying so.
+- Groups are repository-scoped; this is not an organization-wide release lock.
+- Check the symptom in the report: many cancelled publish runs under one group
+  point at a replaced pending slot.
+
+## Publish from the tested artifacts
+
+A publish job that rebuilds can ship something different from what was tested,
+and pays the build twice.
+
+- Build once per publish run (per architecture where a native build differs),
+  pack with `--no-build`, and publish exactly those packages and images.
+- Share build output between jobs of the run as an artifact (see
+  `build-once-and-shard.md`). Do not pull a pull-request run's artifact into a
+  release: artifacts expire and belong to another commit.
+- Build the way consumers' strictest CI builds (`Release`, analyzers on); a
+  `--no-build` pack of a `Debug` build ships the wrong thing.
+- When several services publish images from one build, build the image once,
+  push it, and have the per-service jobs reuse it; compare the per-job pull time
+  against rebuilding from the Docker cache.
+- Keep a version resolved once in an early job and passed down as an output, so
+  every job in the run packs the same version.
+
+## Timeouts and permissions
+
+- Publish and release jobs use a 60-minute `timeout-minutes` tier, per the rule.
+- Grant `contents: write` or `packages: write` on the job that publishes, not on
+  the workflow, and keep build jobs on `contents: read`.
+- Prefer OIDC trusted publishing to a long-lived registry API key where the
+  registry supports it. See `security-and-pinning.md`.
+
+## Speed without weakening the release
+
+- Do not skip validation on the release path to save minutes; move other work off
+  it instead (docs jobs, matrices already covered by schedule).
+- Canary before promotion and recovery disposition are release-method questions;
+  hand them to `cratis-governed-release-methodology`.

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

@@ -0,0 +1,117 @@
+# Required checks, path filters and merge queue
+
+## Contents
+
+- The hang
+- Change detection and the aggregator
+- Keeping required checks stable
+- Merge queue
+
+Use this when skipping work by changed path, when a pull request hangs on a check
+that never reports, or when pull requests that pass alone break the default branch
+together.
+
+## The hang
+
+A required status check that never reports blocks the merge forever. A workflow
+that has a workflow-level `paths:` filter does not start when no path matches, so
+its required check stays pending. A job skipped through `if:` or `needs` reports
+`skipped`, which counts as passing. So: skip jobs, never whole required
+workflows.
+
+## Change detection and the aggregator
+
+Run a cheap `changes` job, gate heavy jobs on its outputs, and require one
+always-run aggregator.
+
+```yaml
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    outputs:
+      code: ${{ steps.diff.outputs.code }}
+    steps:
+      - uses: actions/checkout@v7 # pin by full commit SHA
+        with:
+          fetch-depth: 2
+      - id: diff
+        run: |
+          if git diff --name-only HEAD^1 HEAD | grep -q -v -E '^(Documentation/|.*\.md$)'; then
+            echo "code=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "code=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  build:
+    needs: [changes]
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - run: echo build
+
+  checks:
+    if: always()
+    needs: [changes, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions: {}
+    steps:
+      - name: Require every needed job to pass or be skipped by design
+        env:
+          RESULTS: ${{ toJSON(needs.*.result) }}
+        run: |
+          echo "$RESULTS"
+          if echo "$RESULTS" | jq -e 'any(. == "failure" or . == "cancelled")' > /dev/null; then
+            exit 1
+          fi
+```
+
+- Require only `checks` in branch protection. Adding a job to the workflow then
+  means adding it to `needs`; nothing else changes.
+- `if: always()` is essential: without it the aggregator is skipped when a needed
+  job fails, and a skipped required check counts as passing.
+- List every job in `needs`. `needs.*.result` covers direct needs only, and a
+  job missing from the list can fail unnoticed.
+- The aggregator itself needs a runner, so it adds one scheduling boundary; keep
+  it on a cheap runner with a short timeout.
+- Keep workflow-level `paths:` for workflows nothing requires (a docs site
+  build). For one event, `paths` and `paths-ignore` cannot be combined; use
+  `paths` with `!` negation patterns.
+
+## Keeping required checks stable
+
+Branch protection matches check names. Renaming a job, changing a matrix key or
+moving a job to another workflow removes the old check and leaves the rule waiting
+on a name that no longer exists. When editing, list the check names before and
+after the change and keep them equal, or update the protection rule in the same
+step.
+
+Never make a required check conditional on the thing it validates: release,
+schema, migration and shared-library checks run on every pull request that can
+affect them. If the filter must be wide to be safe, keep it wide.
+
+## Merge queue
+
+Fits when pull requests pass individually and break after merge (semantic
+conflicts), and the cost of a broken default branch is higher than the extra
+validation. It does not shorten CI; it adds a validation of the queued result.
+
+```yaml
+on:
+  pull_request:
+  merge_group:
+    types: [checks_requested]
+```
+
+- The required workflows must run on `merge_group`, or the queue waits forever for
+  a check that never appears.
+- The aggregator must handle both events. For change detection on `merge_group`,
+  compare against `github.event.merge_group.base_sha` instead of `HEAD^1`.
+- Concurrency groups must keep merge-group runs apart from pull-request runs, and
+  must not cancel a merge-group run for a newer pull-request push.
+- Build concurrency, merge-group batching and the queue's own settings are
+  separate controls; change them one at a time.

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

@@ -0,0 +1,65 @@
+# 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
+
+- Cores per job before job count
+- Container images
+- Tools baked into the runner image
+- Cache layers and warm workspaces
+- Publish stages
+
+## Cores per job before job count
+
+Undersized runner pods (a small CPU request or limit) make every job slow, and more
+jobs then multiply the slowness. Before sharding:
+
+1. Print `nproc` and the memory limit at the start of a slow job, and read the
+   runner's resource configuration.
+2. If compile or test steps scale with cores, a larger runner or a higher CPU
+   request is the first lever. Runner capacity is an organization setting; request
+   it from the owner with the measured evidence, do not work around it in YAML.
+3. Re-measure with the same `ci-timings.sh` command.
+
+## Container images
+
+- Start only the services a job uses; pull only those images. Service containers
+  that a pull-request job never touches are pure wait.
+- Pull images in parallel (`docker pull a & docker pull b & wait`, checking each
+  exit status) rather than serially.
+- Do not pull a large release image to obtain one small tool; install or copy the
+  tool directly.
+- Avoid re-pulling a large handoff image in every downstream job; see publish
+  stages below.
+
+## Tools baked into the runner image
+
+Browsers, system packages and language toolchains installed on every run cost
+minutes every run. Bake them into the runner image and keep the install step only as
+a version check. Keep the image's contents versioned so a change is reviewable.
+
+## Cache layers and warm workspaces
+
+Prefer content-addressed caches, which are correct by construction, before
+warm volumes:
+
+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.
+
+Warm workspaces (a prepared checkout and build output on a volume) are only safe
+when they come from a snapshot of a known-good state. Round-robin reuse of
+whichever runner last ran leaves stale or poisoned output. Publish and release
+builds stay cold: a clean build is part of what makes the artifact trustworthy.
+
+## Publish stages
+
+- Run independent stages in parallel, for example build alongside a dependency
+  audit, and join before publishing.
+- Build several images with `docker buildx bake` and a registry cache instead of
+  one serial build per image.
+- When one job builds an image that later jobs consume, keep the handoff small or
+  rebuild from cache, whichever the slowest-steps table shows is cheaper.
+- Keep the publish-path guardrails in `publish-pipelines.md`.

package/package/corpus/skills/cratis-ci-pipeline-performance/references/security-and-pinning.md

@@ -0,0 +1,73 @@
+# Security alongside speed
+
+Use this when a speed change adds or updates an action, edits `permissions:`,
+changes a trigger, or adds a cache. Speed changes widen the blast radius of a
+workflow more often than they narrow it. Run `zizmor` (security audits, including
+`unpinned-uses` and `excessive-permissions`) and `actionlint` (syntax, expressions,
+embedded shell; it does not check pinning) locally on every edited workflow when
+installed. Do not assume CI runs them.
+
+## Contents
+
+- Pin third-party actions
+- Minimal permissions
+- Untrusted code and triggers
+- Caches and artifacts
+- Verification
+
+## Pin third-party actions
+
+A tag can be moved to different code; a full commit SHA cannot. Pin every
+third-party action by its 40-character commit SHA and keep the version in a
+comment so updates remain reviewable:
+
+```yaml
+- uses: actions/checkout@<40-character-sha> # v7
+```
+
+- Resolve a tag to its commit with `gh api repos/OWNER/REPO/commits/TAG --jq .sha`
+  and confirm it matches the release you intend.
+- Examples in this skill show a major tag with a "pin by full commit SHA" note;
+  the major shown is not a recommendation to pin a tag.
+- Actions of the `Cratis` organization follow the owning repository's convention.
+- Let a dependency-update tool bump pinned SHAs so pinning does not freeze them.
+
+## Minimal permissions
+
+- Set `permissions:` at the job level, not the workflow level, and grant only
+  what the job uses. Start from `contents: read`, or `permissions: {}` for a job
+  that touches no repository content.
+- Grant write scopes (`contents`, `packages`, `pull-requests`, `id-token`) only to
+  the job that needs them, such as the publisher.
+- Do not use a personal access token where the workflow token suffices.
+
+## Untrusted code and triggers
+
+- Never check out or run code from a pull request under `pull_request_target`
+  or `workflow_run` with the base repository's credentials: it exposes secrets
+  and a write token to fork code.
+- `pull_request` from a fork has no secrets, which is the safe default for
+  verification.
+- Never route `pull_request` jobs of a public repository to self-hosted runners.
+- Pass untrusted values (branch names, titles, comment bodies) to scripts through
+  `env:`, never interpolated into `run:` with `${{ }}`.
+
+## Caches and artifacts
+
+- Caches must not contain secrets. A cache saved from the default branch is
+  readable by every branch; a cache saved by a pull request is scoped to it.
+- Do not restore a pull-request cache in a privileged workflow.
+- Use `persist-credentials: false` on `actions/checkout` when the job does not
+  push, so the token is not left in the checkout.
+- Artifacts are not private from other jobs in the run; do not put credentials
+  in them.
+
+## Verification
+
+```bash
+actionlint .github/workflows/*.yml
+zizmor .github/workflows/
+```
+
+Pass means exit `0` and no findings. Report a tool that is not installed as not
+run. Resolve findings in the workflow; suppress one only with a recorded reason.

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

@@ -0,0 +1,33 @@
+# Sources and attribution
+
+The structure and method of this skill adapt two MIT-licensed skills. The text
+here is new; no passage is copied.
+
+- `github-actions-efficiency` from github/awesome-copilot, MIT license:
+  https://github.com/github/awesome-copilot/blob/main/skills/github-actions-efficiency/SKILL.md.
+  Adapted: measure before changing, guardrails against hiding required
+  validation, separating repository changes from organization settings, a
+  static-only analysis label, expected against measured savings, and wall clock
+  reported apart from runner-minutes.
+- `ci-speedup` from starslingdev/skills, MIT license:
+  https://github.com/starslingdev/skills/blob/main/skills/ci-speedup/SKILL.md.
+  Adapted: the critical path over required checks, queue delay as a separate
+  signal, shard imbalance, and an always-run aggregator that checks every
+  `needs.*.result`, including for `merge_group`.
+
+Primary documentation consulted for factual claims:
+
+- GitHub Docs, dependency caching, secure use of Actions, concurrency control and
+  merge queue.
+- Docker Docs, GitHub Actions cache backend (custom `scope`).
+- Microsoft Learn, `dotnet test` blame options and Microsoft.Testing.Platform
+  retry and crash/hang extensions.
+- The `actionlint` and `zizmor` project documentation.
+
+- Studio CI investigation (Einar Ingebrigtsen, Cratis, 2026): the method of counting
+  compiles per push, sizing cores before job count, finding test time hidden outside
+  per-test timing, testing each guarantee where it can break, and layering
+  content-addressed caches before warm workspaces. Reduced here to generic levers.
+
+The Cratis-specific levers come from the shared `Cratis/Workflows` cache actions
+and the build-once, artifact and shard layout used in the Arc repository.