@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/cicd/github-actions/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: github-actions
+description: "Author, review, audit, profile, optimize, or debug GitHub Actions workflows (.github/workflows/*.yml): run-history audits, job and step timing, resource bottlenecks, before/after comparisons, conditional CI by changed path, the one required gate check, PR and merge-queue lanes, sharding, workers, caching, self-hosted runners, timeouts, concurrency, permissions and action pinning, post-deploy verification, npm publishing. Use for 'set up CI', 'CI is slow', 'profile CI', 'optimize our pipeline', 'audit CI for redundant or wasted jobs', 'why is this check stuck expected or never started', 'harden this workflow', or 'browser not found on the runner'. NOT for pushing, opening, or merging a PR, or writing CI conventions into CONTRIBUTING.md (github-flow), queue rules or a check unmet inside Mergify (mergify), Playwright config and specs (e2e-test), cloudbuild.yaml or Cloud Run deploys (cloud-build), or which gates a repo must prove (ensure-coverage)."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# GitHub Actions
+
+GitHub Actions verifies; Cloud Build builds and deploys. No workflow deploys to GCP.
+
+## Workflow
+
+For an existing pipeline, use **inspect -> fix -> verify**:
+[inspect-fix-verify guidance](references/audit-profile-optimize.md). Inspect only enough
+source and representative runs to choose an optimization, implement it for fix/optimize
+requests, and verify proportionately. For optimization, start with successful-run timing,
+not the first red job. Keep required checks unchanged. Audit-only requests stay
+read-only; the CLI itself never edits workflows. No report files, evidence tables, run
+archives, or full-history audit are required unless requested or useful to the task.
+Close out with changes, verification, and remaining blockers. Optional examples:
+[ci-case-studies.md](references/ci-case-studies.md).
+Steps 2-7 below describe new workflows or an authorized redesign, not mandatory
+replacement of an established pipeline during an audit or performance-only change.
+
+1. **Profile first.** Use `scripts/ci-run-audit.mjs --profile-run <id>` on a representative
+   successful run. First inspect job/step timings and a compact job graph (names, `needs`,
+   conditions, runners); then read the bottleneck job and its invoked scripts. Locate
+   relevant policy sections instead of loading every CI document. Expand for parallelism,
+   repeated setup, placement, or unnecessary work; use failures when they explain latency
+   or block valid measurement. No justified optimization is a valid outcome, not a reason
+   to invent one.
+   -> [audit-profile-optimize.md](references/audit-profile-optimize.md)
+   Command template -> [two-pass-reading.md](references/two-pass-reading.md)
+2. **Write one `ci.yml`** from the template: `changes` → area jobs → `gate`.
+   → [conditional-ci.md](references/conditional-ci.md)
+3. **Pick the queue** (none, Mergify, GitHub native) and wire its trigger.
+   → [pipeline.md](references/pipeline.md#merge-queue-optional-pick-one)
+4. **Require only `gate`** in branch protection and the queue.
+   → [pipeline.md](references/pipeline.md#the-one-required-check)
+5. **Place jobs on runners**: canonical labels, fork guard, slot-sized parallelism.
+   → [runners.md](references/runners.md)
+6. **Harden**: permissions, pins, inputs through `env:`. → [security.md](references/security.md)
+7. **Add post-deploy and scheduled lanes** if the repo deploys or publishes.
+   → [post-deploy-and-publishing.md](references/post-deploy-and-publishing.md)
+8. **Verify**: `actionlint`; one PR per area runs only that area's jobs; timings meet the SLA.
+   Failures → [debugging.md](references/debugging.md)
+
+## Principles
+
+**Conditional CI**
+- Make CI conditional by default. Trigger backend and frontend jobs by path; skip docs and
+  non-runtime configs.
+- Put no `paths:` on the workflow. Filter inside a `changes` job.
+- For a new design require one `gate` with `if: always()`. During optimization,
+  preserve existing required names unless changing that contract is authorized.
+- Keep live external-service canaries off PRs; bound unavoidable dependency downloads.
+
+**Speed**
+- Run each check once per tree: with a merge queue, no `push: main` or scheduled gate
+  rerun, and each heavy check in one lane. Never skip validation of a changed queue
+  tree. Build once, fan out.
+- Cache downloads: runner-local stores on self-hosted, `actions/cache` on GitHub-hosted.
+  Once downloads are local, the remaining time is repeated work: profile before caching.
+- Keep one type-check gate and one lint gate; turn off the type check and lint inside
+  framework builds in other jobs.
+- Shard E2E.
+- Bound test workers by the slot quota, memory and fixture isolation. Set the count
+  explicitly and measure; never auto-detect host cores inside a container.
+- Parallelize unit tests across cores.
+- Put disposable Postgres on a size-bounded tmpfs by default. Disable durability only
+  when measured and the tests do not require persistence/recovery semantics.
+- Screenshot and trace only failed tests.
+- Give every job `timeout-minutes`; it is the only hang limit, since the queue sets none.
+
+**Merge queue (Mergify)**
+- Open one PR per issue. Enqueue ready PRs together, in one batch.
+- Load the pnpm lockfile once, at admission. Skip the re-load in the queue only with a repo
+  command for it, and never when the batch changed `pnpm-lock.yaml`.
+
+**SLA** (excluding E2E)
+- Mergify: PR admission < 2 min; merge queue < 5 min.
+- Without Mergify: total PR CI < 7 min.
+
+**Security**
+- Set `permissions: contents: read` at the top.
+- SHA-pin third-party actions.
+- Pass `${{ }}` to shell through `env:`.
+- Fail on a missing secret.
+
+**Lanes**
+- Test the deployed revision after deploy, never a local build.
+- Alert on every scheduled or non-PR failure.
+- Never let an AI review be the only gate, or auto-pass it on timeout.
+
+## References
+
+| Read | When |
+|---|---|
+| [audit-profile-optimize.md](references/audit-profile-optimize.md) | Profile the bottleneck, optimize its execution path, verify; expand only as needed |
+| [ci-case-studies.md](references/ci-case-studies.md) | Anonymized CI improvements, measured results, failed experiments and evidence caveats |
+| [conditional-ci.md](references/conditional-ci.md) | Template; path, event, or queue conditions |
+| [pipeline.md](references/pipeline.md) | Lanes, merge queue options, the required check, workflow layout |
+| [speed-and-audit.md](references/speed-and-audit.md) | CI audit, caching, timeouts, concurrency, workers, Postgres |
+| [runners.md](references/runners.md) | Self-hosted fleet |
+| [security.md](references/security.md) | Hardening a workflow |
+| [post-deploy-and-publishing.md](references/post-deploy-and-publishing.md) | Post-deploy verification, npm publishing |
+| [debugging.md](references/debugging.md) | Failed run, missing check, stuck job |
+
+**Hand-offs:** what to prove → `ensure-coverage`; Playwright → `e2e-test`; build and deploy →
+`cloud-build` / `cloud-deploy`; queue config and a stuck queued PR → `mergify`; push, PR,
+merge, and CI conventions in `CONTRIBUTING.md` → `github-flow`.

package/skills/cicd/github-actions/references/audit-profile-optimize.md

@@ -0,0 +1,150 @@
+# Inspect, fix, verify
+
+Use this loop for an existing pipeline. Optimization is the default focus: reduce
+required-check latency or runner consumption while preserving validation, not fix every
+red job or produce an investigation report. For fix/optimize requests, carry through
+implementation and verification within the requested scope. Audit/review-only requests
+stay read-only.
+The CLI only inspects runs; it never edits workflows.
+
+Keep required checks and their meaning intact. Use enough measurements to choose and
+verify a fix, but do not require evidence tables, report files, saved run archives, or
+before/after collections. Persist them only when requested or useful for replay or a
+long-running investigation. Optional examples: [ci-case-studies.md](ci-case-studies.md).
+
+## 1. Profile first, read the bottleneck
+
+Start with a representative successful run in the lane being optimized. Identify the
+required-check critical path and its longest phases, including prerequisite waits and
+setup. For runner-consumption work, identify repeated or unnecessary execution even if
+it is off the critical path. Compare a slow successful run when needed; inspect failed
+runs when retries/infrastructure failures contribute to latency or prevent a valid
+baseline. For an explicit bug-fix request, start with the relevant failure instead.
+
+Read in two passes. First combine job/step timings with a compact workflow map: job
+names, `needs`, conditions, and runners. Then read the chosen bottleneck job's exact
+configuration and invoked commands. For a large workflow or run payload, extract those
+fields/sections before printing it; do not dump the whole file and rely on truncation.
+Expand to other jobs and the required-check/queue contract only when a dependency or
+proposed optimization requires it, including parallelism, repeated setup, or placement.
+Use the [two-pass command example](two-pass-reading.md) to filter before printing.
+
+Honor mandatory repository/domain reading instructions. For other policy documents,
+search headings/keywords for the applicable ADR or CI convention and read that section
+plus necessary context. Do not load every CI document, superseded ADR, or historical
+timing reference by default. Read selectors/reducers when the proposed change affects
+them. Do not turn every optimization into a comprehensive contract review. Use only the
+relevant items of this internal checklist:
+
+- Changed paths select the jobs/specs that actually validate them; shared harness inputs
+  reach their consumers, and unknown paths select broader checks.
+- Intentional skips remain intentional; unexpected skips and incomplete artifacts fail.
+- Required reducers preserve producer failures at the intended failure boundary.
+- Checkout identity, check names, timeouts, cleanup, and execution permissions remain valid.
+
+Inspect the current source revision, not a stale checkout. Compare runs from the same
+lane and comparable change class; do not assume historical runs used current workflows:
+
+```bash
+gh run list --repo owner/repo --workflow ci.yml --limit 10 \
+  --json databaseId,event,headSha,conclusion,createdAt,url
+node "$SKILL_DIR/scripts/ci-run-audit.mjs" --repo owner/repo --profile-run 123456 --json
+# Only when a failure is relevant:
+gh run view 123456 --repo owner/repo --log-failed
+```
+
+Read the slow phase's timing and relevant command, not just a job's red/green status.
+Stop investigating once a useful optimization and bounded change are clear. If no defect
+or worthwhile optimization is established, say so and stop; do not prescribe tuning or
+another measurement campaign by default. Expand history only for an unresolved symptom,
+redundancy question, or an explicitly requested audit:
+
+```bash
+node "$SKILL_DIR/scripts/ci-run-audit.mjs" --repo owner/repo --runs 60
+# Optional replay, not a required deliverable:
+node "$SKILL_DIR/scripts/ci-run-audit.mjs" --repo owner/repo --runs 60 --save runs.json
+node "$SKILL_DIR/scripts/ci-run-audit.mjs" --from runs.json --json
+```
+
+History collection hydrates every requested run; it does not filter by workflow/change
+class. Split PR, queue, scheduled/manual, success, failure, skip, attempt, and runner
+cohorts as relevant. Do not combine unrelated workflows by a shared job name. A failed
+install is not a slow test; a rerun is not an independent code state.
+
+Use audit signals as leads: correlated failures can be a reducer/shared setup failure,
+not redundant coverage; zero catches do not justify removing a rare security/money
+check. `--ignore-job <regex>` can exclude roll-ups from analysis, not substantive tests.
+API head-tree matches do not establish the tested checkout or authorize gate reuse.
+Step-name setup/work labels are heuristic; missing timestamps are not zero.
+Job-created-to-start is a scheduling interval, not necessarily runner contention.
+
+If a single step hides the cause, add minimal timing around the relevant phases only
+(download/link, database readiness, compile, or browser journey). Preserve command exit
+codes, signals, stdout/stderr, and cleanup. Diagnostics must not change the test verdict.
+Never expose secrets or private connection strings. For suspected resource contention,
+inspect actual cgroup quota, throttling, memory/OOM, and I/O; host core count is not the
+slot allotment. Do not collect unrelated resource data by default.
+
+## 2. Fix one concrete cause
+
+Prioritize by the requested objective: required-check latency, runner consumption, or
+reliability. Separate blocked/missing validation, test assertions, infrastructure delays,
+and reporting-only failures. A failed timing upload with passing required gates is not
+automatically the first optimization; establish its impact before diverting the task.
+If broken validation prevents a meaningful baseline, repair that blocker within scope
+before comparing performance. Do not expand into unrelated product bugs.
+
+Choose the smallest justified code/config change. If the cause belongs to a shared
+gateway or runner, hand off to its owner rather than patching unrelated repository code.
+Shorter retries can reduce failure latency without improving successful-run performance
+or reliability; do not present faster failure as a speedup or raise timeouts as a fix.
+
+Separate a candidate from a ready patch. Visible setup cost does not prove caching pays
+off; observed start delay does not identify its cause. If one unresolved fact determines
+the choice, check that fact within scope or name the single missing check and stop. For
+example, compare cache transfer cost with install time, or distinguish a concurrency
+mutex from runner availability. Do not turn a candidate into a patch or another broad
+investigation. No justified change remains a valid outcome.
+
+| Bottleneck | Candidate change | Safeguard |
+|---|---|---|
+| Unrelated suites run | path/spec selection; classify before heavy service setup | shared dependencies fan out; unknowns run broader checks; preserve required names |
+| Many tiny setup-heavy jobs | combine compatible checks or overlap independent commands | preserve each exit status and the required-check contract |
+| Repeated or unreliable dependency work | local download store, working gateway, bounded downloads | frozen/hash-verified installs; no credentials in logs |
+| Ineffective cache | remove expensive transfer or cache downloads only | compare transfer cost with install/build savings |
+| CPU oversubscription | quota-sized workers and balanced shards | check memory, throttling, and fixture isolation; do not copy fleet worker counts |
+| Scratch DB disk cost | size-bounded tmpfs (default); optional durability reduction | measure benefit; never weaken persistence/recovery tests; respect memory budget |
+| Slow test-DB preparation | one session for the prepare scripts, parallel independent ones, or a snapshot keyed on schema+prepare inputs | tmpfs alone does not fix round-trip-bound SQL; the snapshot key covers every input |
+| Same check in every job (type check, lint, lockfile policy) | one standalone gate; turn the copy off in builds; run policy checks only when their inputs change | keep the single gate required; never drop the check from CI |
+| Slow/silent failures | inner timeout and retained partial diagnostics | outer headroom; cleanup always; incomplete validation never passes |
+| Main repeats queue proof | remove the `push: main` / gate `schedule:` trigger | the queue ran the exact tree; keep deploy and post-deploy workflows |
+
+Do not suppress gates, drop tests without replacement validation, add
+`continue-on-error`, or raise timeouts merely to make CI look healthy. Changed queue
+trees still need validation. For selectors, test behavior across affected/shared paths,
+docs, rename preimages, deletions, unknowns, malformed metadata, and unexpected skips
+as relevant to the change. Tests should not merely restate workflow YAML.
+
+## 3. Verify proportionately
+
+Run affected script tests and `actionlint` after workflow edits. For selectors/reducers,
+include the missed path or failure boundary that motivated the fix. Inspect a comparable
+PR/queue run when available; do not dispatch extra workflows outside the requested scope.
+For performance changes, compare the formerly slow phase under comparable lane, runner,
+and cache conditions. Expand the sample only when needed to decide whether the change
+helps. Check that it did not move the bottleneck or increase shared runner contention.
+
+Close out briefly: what changed, what was verified, and remaining blockers. A useful run
+link or timing is enough; no mandatory report template or archive. State when CI or live
+remeasurement was unavailable. Distinguish a static risk from a reproduced failure and
+an expected improvement from a measured one. Small samples do not prove fleet tail
+latency or sustained speedup. Keep or revert according to the task's objective.
+
+## Boundaries
+
+- Queue membership, dequeue causes and evidence-reuse rules: `mergify`.
+- Which journeys must remain release-blocking: `golden-path` / `ensure-coverage`.
+- Playwright specs and fixtures: `e2e-test`.
+- Fleet quota, gateway injection and persistent stores: fleet owner;
+  [runners.md](runners.md) describes the interface, not permission to reconfigure hosts.
+- Cloud Build deployment or promotion: `cloud-build` / `cloud-deploy`.

package/skills/cicd/github-actions/references/ci-case-studies.md

@@ -0,0 +1,141 @@
+# CI case studies: two anonymized repositories
+
+Historical audit of two repositories, using remote default-branch source, change history,
+PR reports and native GitHub jobs/logs. Local checkouts were stale and were not changed.
+These examples inform [audit-profile-optimize.md](audit-profile-optimize.md); they do
+not authorize changing another repository's required proof or copying private endpoints.
+
+Repository names, organizations, URLs, commit hashes, PR/run identifiers and exact
+calendar dates are omitted. Original audit records remain outside the distributed skill;
+no identifying source map is included here. Review follow-up fixes and reversions, not just
+the first optimization commit. No benchmarks, browser journeys, timeout drills or live
+ruleset/IAM checks were rerun for this audit.
+
+**Superseded (2026-10-10):** where these studies weigh reusing queue evidence on main, the
+decided answer is to drop the `push: main` rerun entirely, not to reuse evidence
+(`mergify` skill, "The Queue Run Is The Integration Run").
+
+## Evidence vocabulary
+
+- **Live observation:** native timestamps, check results or inspected logs. Different
+  batches/scopes/hosts are not a controlled before/after comparison.
+- **Controlled benchmark:** attributed to the change author's recorded experiment;
+  not independently reproduced in this audit. Include resource limits/sample counts.
+- **Replay/model:** historical path selection, estimated shard loads or fleet simulation.
+  Useful for choosing an experiment, not an achieved speedup.
+- **Configuration:** implemented mechanism, without isolated performance measurement.
+
+## Repository A: multi-area application
+
+Changes across several consecutive optimization iterations:
+
+| Improvement | Reusable practice | Evidence and constraint |
+|---|---|---|
+| Affected-area functional selection, dedicated browser selection, helper correction | Select product areas plus importer/helper dependencies; retain app-shell coverage and strict reducers | **Live:** two queue runs used one rather than five functional shards. Unknown/shared inputs and >=60% modeled suite cost run full. Unmeasured tests get 5s, not zero. Missing selection flags and unexpected skipped jobs fail. Parser coverage is not a complete runtime dependency graph. |
+| Curated golden-path selection, following engine migration | Check executable test selection after replacing machinery; file tags alone can run excess tests | **Author benchmark:** 76 -> 39 tests, 409.3s -> 262.6s; all 21 queue-local paths ALIVE. CI gain is not isolated. Missing/skipped paths cannot pass; this does not prove a deployed environment. |
+| Retained timeout diagnostics | Write logs directly to a retained bind mount before termination | **Configuration:** EXIT traps may never copy logs after a timeout. Existing `!cancelled()` uploads do not guarantee evidence after whole-job cancellation or runner loss. |
+| Prisma mirror restoration and unified gateway | Route downloads consistently; keep pinned/frozen/checksum verification | **Author probe:** pinned 8.9-MB engine downloaded in ~2s with matching checksum. No end-to-end gain isolated. LAN routing/HTTP trust is fleet-specific; Cloud Build is a different environment. |
+| One owner for deploy-tooling checks | Move a repeated suite with complementary, tested execution-profile conditions | **Historical cost:** 46-107s in PostgreSQL. Queue/manual policy owns the suite; main/diagnostic PostgreSQL retains it when policy is absent. Every profile still has an owner and required verdict. |
+| 8-CPU quotas and two unit shards, rollback to four workers | Reduce repeated setup, then tune workers under actual quota and fixture constraints | **Author failure analysis:** six workers had 3 failures/28 jobs, four had 0/8. Current unit matrix is two shards x four workers. This is not a universal worker count; browser fixtures still require one worker. |
+| Overlapping policy checks and test-only timeout reduction | Start independent commands together; explicitly await each result | **Author benchmark:** timeout test 30.2s -> 2.3s; tooling ~80s -> ~51s. Missing/unreadable status fails. Timeout override can only shorten collection; uncertainty still conservatively builds. |
+| Full same-tree queue evidence reuse on main | Reuse only exact-tree, complete, trusted latest-attempt proof | **Live:** one main run skipped disposable PostgreSQL/full functional work but refreshed external checks. Missing evidence reruns. Scoped `N/M` jobs cannot satisfy the full numbered-shard evidence contract. |
+| Duration-balanced shards | Deterministic longest-processing-time assignment from measured medians; refresh unknown timings | **Model:** ~160s test load/shard. Full jobs still varied 281-495s in one full-suite run; setup and scheduling remain separate costs. Empty/mismatched suite listings fail. |
+| Request long-lane runners first | Explore scheduling contention before adding execution workers | **Simulation only:** a 15s head start and wider smoke dispatch were modeled to improve queue latency. FIFO is not guaranteed; a later shard still waited 350s. Do not copy sleeps as a proven fix. |
+
+### What the live sample proves
+
+Listed 60 recent CI runs; hydrated 14 selected first-attempt runs (seven queue, four
+admission, three main) and inspected five failure logs. Gate timestamps were checked
+against the matching check suite. Clock: run creation -> applicable required gate,
+not last `updated_at` or time waiting inside Mergify.
+
+| Observation | Interpretation |
+|---|---|
+| Scoped A / scoped B: 3.6-4.0 functional job-minutes versus 24.3-36.3 across five earlier full runs | Confirmed workload reduction across different batches, not controlled latency savings. |
+| Their gates took 7m41s / 13m29s | PostgreSQL / golden-path case lifecycle became the remaining critical jobs. Smaller workload need not shorten the gate. |
+| Four admission gates: 5m16s-7m45s; six of seven queue gates >10m | Above repository targets in this sample, but not its official last-20-run p90. Its browser-inclusive budget differs from this skill's generic budget. |
+| Both following main runs executed the full disposable suites | Scoped queue evidence correctly did not authorize broad main reuse. This shifts some detection after merge; it is an explicit coverage-policy tradeoff, not proof of selector completeness. |
+| Latest audited main failed database timestamp ordering, UI presentation checks, and external authentication | Verified failure signatures, not diagnosed causes or proof the optimizations caused regressions. No sustained reliability win established. |
+
+**Remaining decisions:** validate selector recall and reconcile broad-before-merge policy
+with scoping; investigate current failures; collect a full SLA window; drill timeout
+artifacts. Main concurrency permits cancelling older validation, unlike this skill's
+default policy. Do not transfer that exception without deciding which exact-SHA evidence
+must be retained. Preserve the repository's budget contract and engine evidence boundary.
+
+## Repository B: authenticated web application
+
+Changes across several consecutive optimization iterations:
+
+| Improvement | Reusable practice | Evidence and constraint |
+|---|---|---|
+| Affected-path lanes | Independently select schema, unit/integration/release, migration, Smoke and authenticated work | **Replay:** schema selected 8/18 validation-relevant commits; release 5/18. Projected savings only. The implementation's shared-tooling diff correctly ran all lanes. Unknown/invalid evidence selects all; preserve existing required names and strict verdicts. |
+| Shared golden-path engine | Replace duplicate gate machinery with a versioned contract and target profiles | **Configuration/correctness:** `run` may return zero with failed paths; `verdict` is blocking. Deployed profiles stay read-only and correlate the candidate SHA; queue-local seed credentials are not deployment proof. |
+| Consistent dependency gateway | Configure package-manager bootstrap and rewrite explicit lockfile tarball hosts | **Configuration:** a registry variable alone need not reroute pinned tarballs. Preserve frozen fetch/offline install and Prisma checksums. Private gateway addresses are not portable defaults. |
+| Verified docs-only queue skip | Diff the whole speculative batch, including new branch creation and later pushes | **Historical replay**, not newly measured live skip savings. Require exact checkout, unique supported base and rename preimages. Runtime-served Markdown still validates. Invalid evidence runs all; detector/verdict jobs explicitly install Node. |
+| Worker cap and pinned image reuse | Bound Next workers instead of trusting host CPU visibility; inspect immutable images before pulling | **Controlled author ABBA benchmark:** cold build mean 85.681s -> 73.051s (14.7%); local image inspect <1s versus pull 4s. Authenticated browser workers remain one/shard because fixtures are shared. |
+| Next startup/resource profiler | Measure launch/banner/compile/TypeScript/exit and cgroup deltas before choosing a fix | **Instrumentation:** controlled startup was 0.55-0.64s; lazy-config experiment did not help. Preserve output/status/signals; bound parsing and label unavailable counters. Cgroup deltas include the enclosing build, not each phase independently. |
+| tmpfs PostgreSQL and phase timing | Separate image, launch, readiness and cleanup; use bounded scratch storage | **Controlled author benchmark:** 13.5s disk -> 1.8s tmpfs, two samples each. Durability-off added no demonstrated startup benefit, so Smoke/schema retained default durability. Disposable targets only; tmpfs counts toward memory limits. |
+| Remove healthy-path probes/build archives | Measure cache transfer/hit eligibility and successful-install diagnostic overhead | **Controlled author benchmark:** warm install 7.793s -> 4.142s (46.9%). Retain failure-only diagnostics/retries/status. Cross-batch archive eligibility was ineffective. Compiler caching persisted a generated secret canary in plaintext: audit contents, not only speed. |
+| Owned four-way integration shards | Parallelize inside a job with a private migrated/seeded database per process | **Controlled author benchmark, 8 CPU/16 GiB:** durable serial 323.6s; tmpfs serial 214.6s; final sharded 75.2s including setup/cleanup. Explicit disposable loopback targets, atomic durable ownership, bounded connections and signal cleanup prevent deleting the base/foreign database. |
+
+### What the live sample proves
+
+Hydrated 15 selected run/job payloads and four logs. Elapsed here is creation -> final
+job completion, not official required-gate latency; these samples are not fleet p50/p90.
+
+| Observation | Interpretation |
+|---|---|
+| Latest PR CI 8m12s versus prior PR 4m45s; unit jobs 236s/235s | Similar execution, different wait. After detection, newest jobs waited ~128-149s to start. Different trees/load: do not attribute this to path selection. |
+| Latest authenticated queue 9m13s; builds 45-129s | Repeated setup/build and browser work both matter. Critical shard pre-banner 20.254s versus concurrent Smoke 2.343s exposes variability, not its cause. |
+| Queue Smoke job 213s; main Smoke 169s, the same Git tree | Confirmed repeated execution. Repository B's policy still requires both: reuse is a decision, not an implemented optimization here. |
+| Post-deploy 9m50s; deployment poll 317s; smoke execution 18s | Optimizing browser execution alone misses the main wait. Preserve exact-SHA deployed-candidate correlation independently of queue proof. |
+| An earlier CI run, Smoke and authenticated jobs failed at Prisma generation | Inspected logs show mirror checksum-download `socket hang up`. Shared infrastructure failure is not redundant coverage or necessarily a test flake; later green samples do not prove permanent remediation. |
+
+**Remaining decisions:** profile variable startup/dispatch, validate narrow-path skips,
+decide whether main reuse is compatible with policy, and investigate dependency
+reliability. Repository guide cache/proxy text was stale relative to executable source.
+Build-once/fan-out across authenticated shards needs an artifact/environment/secret
+review, not a mechanical cache change. Required job names differ from the skill's
+single-gate design: preserve them during a performance-only change.
+
+## Repositories C and D: monorepos on a warm LAN fleet
+
+A later measured audit of two pnpm monorepos on self-hosted runners with a LAN package
+proxy and persistent per-slot stores. **Live observation** from step timings and install
+logs; fixes were proposed from these numbers, not yet remeasured.
+
+| Finding | Reusable practice |
+|---|---|
+| Installs 4–19 s; install logs showed warm store reuse in most jobs | Downloads were solved; remaining time was repeated work. Profile before adding caches |
+| Framework build type-checked in 5 test shards (49 s each) plus the build job (22 s); the incremental `tsc` gate took ~5 s | One type-check gate; CI-only flag off in builds; check the gate's tsconfig covers the same files |
+| Lockfile policy check 35–41 s, ~80% of install | Run when the lockfile or policy inputs change from a verified base |
+| Service `--health-interval 10s` cost ~15 s per job | Poll every 1–2 s, retries preserving the total timeout |
+| 27–49 s of sequential SQL prepare scripts in 13 jobs, database already on tmpfs | Round-trip bound: batch, parallelize or snapshot |
+| Per-build SHA `ARG` above `pnpm install` missed the 54 s install cache every build | Declare per-build args after installs (`docker` skill) |
+
+## Transferable rules
+
+1. List cheaply; hydrate representative successful runs. Inspect a failing outlier only
+   when it explains delay or blocks measurement. Snapshots are optional when requested
+   or useful for replay; expand for distributions rather than claiming p90 from a small sample.
+2. Report separate gate, scheduling, execution and runner-minute clocks. Label setup
+   heuristics and cumulative milestones. Neither is a CPU profile or Mergify queue wait.
+3. Bound workers by actual quotas and fixture isolation; measure setup before adding
+   shards. Unknown tests need nonzero estimates. Review failed experiments and reversions.
+4. Omission, relocation and reuse each need a fail-closed contract: complete selected
+   checks, one suite owner, exact provenance and fresh environment-sensitive evidence.
+5. Keep diagnostics subordinate to command correctness and outside disposable processes.
+   Test missing status, timeout, unexpected skip and cleanup ownership, not YAML strings.
+6. Judge caches by net cost, cross-run eligibility and secret safety. A frozen install
+   remains required even with a local store or gateway; addresses/trust stay fleet-owned.
+7. Optimize an evidenced bottleneck, then remeasure equivalent cohorts. Configuration,
+   simulated savings and same-tree repeats are not authority to weaken required gates.
+
+## Evidence provenance
+
+Identifying citations are intentionally excluded from this anonymized reference. The
+original audit used source snapshots, change reports and selected native CI jobs/logs.
+Benchmark figures remain author-reported, not independently reproduced; live samples
+remain observations across different batches. These examples are historical lessons,
+not verifiable gate receipts or a substitute for collecting evidence in the target repo.

package/skills/cicd/github-actions/references/conditional-ci.md

@@ -0,0 +1,214 @@
+# Conditional CI
+
+> Read when: running jobs only for some changed paths (backend / frontend), events, or the
+> merge queue.
+
+## Workflow
+
+1. Run the workflow on every `pull_request` (Mergify's queue drafts arrive this way too) and
+   on `workflow_dispatch`. Put no `paths:` on it. Add `push: main` only in a repo without a
+   merge queue; with one, the queue run already tested the exact tree (`mergify` skill,
+   "The Queue Run Is The Integration Run").
+2. Add a `changes` job with `dorny/paths-filter`: one filter per area (`backend`,
+   `frontend`), shared files (lockfile, root config, `ci.yml`) anchored into each area. Leave
+   docs and non-runtime configs out of every filter.
+3. Give each area job `needs: changes` and `if: needs.changes.outputs.<area> == 'true'`.
+4. Run network-dependent canaries only on demand: `if: github.event_name == 'workflow_dispatch'`.
+   A recurring canary goes in its own scheduled workflow, never as a scheduled rerun of `gate`.
+5. Run slow suites only in the queue: `if: startsWith(github.head_ref, 'mergify/merge-queue/')`.
+6. Add one `gate` job: `if: always()`, `needs:` every job, allow a skip only when that job's
+   condition was false. Require only `gate`.
+7. Before merging, open one PR per area and confirm only that area's jobs run and `gate` passes.
+
+## Template
+
+Runners are GitHub-hosted for brevity; on the self-hosted fleet use the labels and fork guard
+in [runners.md](runners.md).
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+  workflow_dispatch:   # the canary; no push: main or schedule: rerun of the gate
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  changes:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      backend: ${{ steps.filter.outputs.backend }}
+      frontend: ${{ steps.filter.outputs.frontend }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: filter
+        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        with:
+          filters: |
+            shared: &shared
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - '.github/workflows/ci.yml'
+            backend:
+              - *shared
+              - 'apps/api/**'
+              - 'packages/db/**'
+            frontend:
+              - *shared
+              - 'apps/web/**'
+              - 'packages/ui/**'
+
+  backend:
+    needs: changes
+    if: needs.changes.outputs.backend == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - run: pnpm --filter api test
+
+  frontend:
+    needs: changes
+    if: needs.changes.outputs.frontend == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - env:
+          SHARD: ${{ matrix.shard }}
+        run: pnpm --filter web exec playwright test --shard="$SHARD/3"
+
+  e2e-full:
+    needs: changes
+    if: >-
+      startsWith(github.head_ref, 'mergify/merge-queue/') &&
+      (needs.changes.outputs.backend == 'true' || needs.changes.outputs.frontend == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - run: pnpm test:e2e:full
+
+  canary:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - env:
+          EXTERNAL_NETWORK: '1'
+        run: node --test test/*.canary.mjs
+      - if: failure()
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh issue create --repo "$GITHUB_REPOSITORY" \
+            --title "CI canary failed on $GITHUB_REF_NAME" \
+            --body "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+
+  gate:
+    if: always() && github.event_name == 'pull_request'
+    needs: [changes, backend, frontend, e2e-full]
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - env:
+          CHANGES: ${{ needs.changes.result }}
+          BACKEND: ${{ needs.changes.outputs.backend }}
+          FRONTEND: ${{ needs.changes.outputs.frontend }}
+          IN_QUEUE: ${{ startsWith(github.head_ref, 'mergify/merge-queue/') }}
+          BACKEND_RESULT: ${{ needs.backend.result }}
+          FRONTEND_RESULT: ${{ needs.frontend.result }}
+          E2E_FULL_RESULT: ${{ needs.e2e-full.result }}
+        run: |
+          set -uo pipefail
+          fail=0
+          # check <job> <result> <expected to run: true|false>
+          check() {
+            case "$2" in
+              success) echo "ok   $1" ;;
+              skipped) if [ "$3" != true ]; then echo "skip $1"
+                       else echo "::error::$1 skipped but its paths changed"; fail=1; fi ;;
+              *)       echo "::error::$1: $2"; fail=1 ;;
+            esac
+          }
+          code=false
+          if [ "$BACKEND" = true ] || [ "$FRONTEND" = true ]; then code=true; fi
+          full=false
+          if [ "$IN_QUEUE" = true ] && [ "$code" = true ]; then full=true; fi
+          [ "$CHANGES" = success ] || { echo "::error::changes: $CHANGES"; exit 1; }
+          check backend  "$BACKEND_RESULT"  "$BACKEND"
+          check frontend "$FRONTEND_RESULT" "$FRONTEND"
+          check e2e-full "$E2E_FULL_RESULT" "$full"
+          exit "$fail"
+```
+
+Shared setup, `.github/actions/setup/action.yml`:
+
+```yaml
+name: setup
+description: Node, pnpm, and dependencies
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+    - shell: bash
+      run: corepack enable
+    - shell: bash
+      run: pnpm install --frozen-lockfile
+```
+
+## Principles
+
+- Condition jobs, never the workflow or the required check.
+- Require exactly one check, `gate`. Never rename it without updating the queue config.
+- Give `gate` `if: always()`. Fail it on `failure`, `cancelled`, a failed `changes` job, or a
+  skip whose condition was true.
+- Run a job only when a rule matches it. Write the rules; add a path to a filter when it should
+  trigger a job.
+- Anchor shared files (lockfile, root config, `ci.yml`) into every area they affect.
+- Compare outputs with `== 'true'`.
+- Condition by event before condition by path.
+- Keep network fetches off the PR lane. Name those tests `*.canary.*`; require an opt-in env
+  var to run them; open an issue when they fail.
+- Add extra queue-only suites for work too slow for every PR push. Avoid redundant
+  suites, but still prove a changed combined queue tree; a PR's earlier pass alone is
+  not that proof. Preserve existing required checks when optimizing an established repo.
+- Discover tests by glob, never by hand list. Fail on an empty selection.
+- Pass expressions to shell through `env:`. Never inline `${{ }}` in `run:`.
+- SHA-pin third-party actions.
+
+## Review checklist
+
+- [ ] No `paths:` / `paths-ignore:` on the workflow
+- [ ] `gate` is the only required check, with `if: always()`, and checks every job it needs
+- [ ] Each area job's `if:` names its filter output with `== 'true'`
+- [ ] Shared files are in every affected filter
+- [ ] Network jobs skip PRs and alert on failure
+- [ ] With a merge queue: no `push: main` or `schedule:` rerun of the gate
+- [ ] Each queue-only job runs something PR jobs don't
+- [ ] One PR per area confirmed only that area's jobs ran

package/skills/cicd/github-actions/references/debugging.md

@@ -0,0 +1,13 @@
+# Debugging
+
+> Read when: a run failed, a check never started, or a job is stuck queued.
+
+- Failed run: `gh run view <id> --log-failed`; list with `gh run list -w ci.yml -b <branch>`.
+- **Check "expected" forever** → the workflow never started: path filter, missing
+  `merge_group` trigger, draft skip, or a renamed job. Not a test failure.
+- **Queued job never starts** → no runner matches the label set (typo, retired label) or all
+  slots are busy: `gh api repos/{owner}/{repo}/actions/runners`.
+- **Skipped and treated as failure** → the gate's allowed-skip rule. Read the gate step output.
+- Queue/dequeue questions → `mergify` skill; `gh pr checks` can't see a dequeue.
+- Validate locally: `actionlint` for syntax and expression mistakes; `act` for simple jobs
+  (not for self-hosted or service-container jobs).