@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-benchmarking/references/priority-findings-20261006.md

@@ -0,0 +1,115 @@
+# CPU priority findings: 2026-10-06
+
+Read this record before answering whether negative, zero or positive nice values
+improved the tested workload. Reuse these results for the same question; a new
+experiment needs a materially different workload, contention regime or hypothesis.
+Follow the host's authorization rules before changing priority or measuring again.
+
+## Result and scope
+
+Negative nice did not establish a timing or memory benefit in this small WSL
+allocation experiment. Verified effective nice 0 was the only setting that met
+the preset variation criterion for both runtimes. It is a baseline candidate for
+comparable isolated measurements, not a universal priority policy.
+
+The workload performed 16,384 warmup and 65,536 measured `Buffer.alloc(size, 1)`
+operations, cycling 1,000, 16,000, 128,000 and 1,000,000-byte buffers and retaining
+at most 128 references. Timing and CPU cover the measured loop; peak RSS covers
+the whole process. This allocation case is also reported in
+[Bun issue 44661](https://github.com/oven-sh/bun/issues/44661).
+This is a priority sensitivity comparison, not a general Bun-versus-Node ranking,
+a contention-resistance test or an explanation of that issue's root cause.
+
+## Recorded experiment
+
+The measured interval was 2026-10-06 23:42:55Z–23:45:40Z. Bun 1.4.2 and
+Node 26.10.0 used unchanged sources and binaries. Three independent processes
+per runtime/priority cell ran in counterbalanced order, for 24 processes total.
+All passed correctness, effective-control and quiet-host admission checks;
+none was rejected. The preset criterion was `(maximum - minimum) / median <= 10%`.
+
+Controls were Windows-hosted WSL, Linux kernel 7.2.8 with an unverified custom
+scheduler implementation, ordinary fair scheduling, unprivileged workload UID
+1000, CPU affinity 0–7 and identical 704 MiB `memory.high`/`memory.max` limits.
+No CPU quota was present at inspected cgroup ancestors. The launcher set absolute
+priority before dropping privileges and verified it afterward; the workload did
+not run as root. Main-thread scheduler wait included warmup and cannot establish
+timed-region or all-GC-thread scheduling effects.
+
+| Runtime | Nice | Median wall ms | Wall range ms |   Span | Median CPU ms | Median peak RSS MiB | Variation passes |
+| ------- | ---: | -------------: | ------------: | -----: | ------------: | ------------------: | ---------------- |
+| bun     |  +10 |         1445.9 | 1195.6–1467.9 | 18.83% |        1812.3 |               191.5 | no               |
+| bun     |   +0 |         1356.4 | 1326.5–1412.4 |  6.34% |        1778.9 |               191.3 | yes              |
+| bun     |  -10 |         1416.1 | 1291.2–1468.1 | 12.49% |        1781.2 |               189.2 | no               |
+| bun     |  -20 |         1346.1 | 1287.4–1497.2 | 15.58% |        1691.4 |               190.1 | no               |
+| node    |  +10 |         1196.5 | 1083.8–1231.8 | 12.37% |        1849.8 |               193.5 | no               |
+| node    |   +0 |         1136.2 | 1133.3–1138.5 |  0.46% |        1735.8 |               192.1 | yes              |
+| node    |  -10 |         1148.1 | 1097.3–1152.7 |  4.82% |        1747.0 |               191.9 | yes              |
+| node    |  -20 |         1191.7 | 1189.9–1277.3 |  7.33% |        1825.9 |               192.7 | yes              |
+
+Bun +10, -10 and -20 failed the variation criterion. Node -10 overlapped nice 0;
+Node -20 was slower. These three-process samples support no confirmed negative
+priority gain. The small quiet-host cohort does not predict behavior under
+contention or on another scheduler. The per-process measurement values below
+make the reported aggregates auditable; their scope limits still apply.
+
+## Per-process measurement values
+
+These are the 24 retained output measurements used above, with path and process
+identity fields omitted. Repetition numbers identify each process within its
+runtime/priority cell; they are not execution order. CPU is in microseconds and
+peak RSS in KiB to retain the source units. Wall values retain nine decimal
+places for aggregate recalculation, not a claim of clock accuracy.
+
+Recalculation from these samples matches every aggregate before display rounding.
+Each source output passed correctness and effective-control checks before and
+after the workload. No process was rejected. The broader host-admission receipts
+remain outside this bundle; this table provides sample-level auditability for
+the reported wall, CPU, RSS and variation values, not complete host reproduction.
+
+| Runtime | Nice | Repetition |        Wall ms |  CPU us | Peak RSS KiB |
+| ------- | ---: | ---------: | -------------: | ------: | -----------: |
+| bun     |  +10 |          1 | 1195.596419000 | 1505936 |       196116 |
+| bun     |  +10 |          2 | 1445.887323000 | 1812345 |       190948 |
+| bun     |  +10 |          3 | 1467.863081000 | 1852217 |       197132 |
+| bun     |   +0 |          1 | 1326.456355000 | 1659644 |       195900 |
+| bun     |   +0 |          2 | 1412.394017000 | 1778913 |       189540 |
+| bun     |   +0 |          3 | 1356.414170000 | 1779749 |       199772 |
+| bun     |  -10 |          1 | 1291.186539000 | 1638686 |       190644 |
+| bun     |  -10 |          2 | 1468.095042000 | 1847875 |       195332 |
+| bun     |  -10 |          3 | 1416.096128000 | 1781215 |       193692 |
+| bun     |  -20 |          1 | 1287.427399000 | 1628746 |       194676 |
+| bun     |  -20 |          2 | 1497.167736000 | 1893806 |       191196 |
+| bun     |  -20 |          3 | 1346.090557000 | 1691437 |       195036 |
+| node    |  +10 |          1 | 1083.811791000 | 1655921 |       200988 |
+| node    |  +10 |          2 | 1196.507378000 | 1849814 |       198100 |
+| node    |  +10 |          3 | 1231.812016000 | 1913550 |       197184 |
+| node    |   +0 |          1 | 1138.547173000 | 1717254 |       196524 |
+| node    |   +0 |          2 | 1136.151985000 | 1735839 |       197480 |
+| node    |   +0 |          3 | 1133.265512000 | 1736305 |       196716 |
+| node    |  -10 |          1 | 1097.328563000 | 1684817 |       196008 |
+| node    |  -10 |          2 | 1152.692612000 | 1789165 |       197780 |
+| node    |  -10 |          3 | 1148.141853000 | 1746972 |       196516 |
+| node    |  -20 |          1 | 1277.348138000 | 1994581 |       196600 |
+| node    |  -20 |          2 | 1191.670413000 | 1825925 |       197344 |
+| node    |  -20 |          3 | 1189.945316000 | 1821113 |       198976 |
+
+## Omitting nice versus requesting zero
+
+A child inherits its parent's nice value, and `exec` preserves it. Omitting
+`nice` therefore yields zero only when the parent already has effective nice 0.
+GNU `nice -n 0 COMMAND` adds zero to the inherited value; it does not reset +10
+to zero. Bare `nice COMMAND` applies the default +10 adjustment. `setpriority`
+sets an absolute value, subject to permissions; verify the effective value
+rather than treating the requested command as proof.
+
+Positive nice lowers CPU scheduling priority; negative nice raises it. Neither
+reserves a core or replaces host admission and resource controls. Keep effective
+values equal across ordinary comparison arms. General +10 background/build
+policies serve responsiveness and are separate from this experiment; these
+results do not authorize removing them or changing installed settings.
+
+Sources: [Linux getpriority/setpriority](https://man7.org/linux/man-pages/man2/setpriority.2.html)
+for inheritance, absolute values and permissions; [GNU nice](https://www.gnu.org/software/coreutils/manual/html_node/nice-invocation.html)
+for relative adjustment. GNU online retrieval was unavailable during verification;
+the installed command's help confirmed the adjustment and default +10.

package/skills/hr-benchmarking/references/tools.md

@@ -0,0 +1,160 @@
+# Benchmarking and investigation tools
+
+These defaults come from tools used in our work. Prefer a suitable runner
+already used by the project. Check the official version's documentation before
+relying on flags or interpreting output.
+
+## Timing and resource measurement
+
+| Task                               | Default and reason                                                                                                                                     | Limits to record                                                                                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Whole CLI commands                 | [Hyperfine](https://github.com/sharkdp/hyperfine): repeated runs with wall time, CPU time and peak memory, warmup/preparation and JSON output.         | Works across Linux, macOS and Windows. Declare warm/cold conditions. Since 2.0 commands run without a shell unless `-S` or `--shell` is given; 1.x needs `-N` for that. Peak memory and `--metrics` hardware counters are measured on Linux and macOS only; on Windows use another tool for memory. Check `schema_version` before reading exported JSON; 2.0 changed its layout. |
+| JavaScript operations              | [Tinybench](https://github.com/tinylibs/tinybench), directly or through the project's benchmark runner: warmup and task latency/throughput statistics. | The unit is a task invocation. For 1,000-operation batches, batch p99 divided by 1,000 is the p99 of batch-average costs, not mean operation cost or individual-operation p99.                                                                                                                                                                                                   |
+| HTTP load, including JS/TS servers | [oha](https://github.com/hatoo/oha): a native load generator with concurrency/rate controls, latency distributions and JSON output.                    | Declare protocol, connections, rate, deadlines, keepalive and error handling. Check generator CPU/network limits. Latency correction requires rate limiting with `-q`.                                                                                                                                                                                                           |
+| Command CPU and memory             | [GNU time](https://www.gnu.org/software/time/manual/time.html), commonly `/usr/bin/time -v`: wall time, CPU and maximum RSS.                           | GNU options differ from shell `time` and BSD/macOS tools. RSS is a lifetime high-water mark for the observed process; it does not isolate retained cache memory.                                                                                                                                                                                                                 |
+| Host or process contention         | Linux [mpstat/pidstat](https://github.com/sysstat/sysstat): processor utilization and process CPU, memory and I/O observations.                        | Sampling can miss short bursts; some counters need kernel support. These explain interference, not application latency.                                                                                                                                                                                                                                                          |
+
+On Linux with compressed swap enabled, observe compressed-swap activity as
+well as disk swap I/O. Unchanged `pswpin`/`pswpout` counters do not establish
+absence of swapping. For [zswap](https://www.kernel.org/doc/html/latest/admin-guide/mm/zswap.html),
+record available `zswpin`/`zswpout`/`zswpwb` deltas from the benchmark cgroup's
+`memory.stat` over the measured interval. Label host-wide deltas as system-wide;
+they cannot attribute activity to the workload.
+
+Use [cgroup swap and zswap accounting](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v2.html)
+(`memory.swap.current`, `memory.zswap.current`) to distinguish the workload
+from other jobs. These occupancy values do not measure activity by themselves.
+Record missing counters and preserve the run plan's declared pressure criteria.
+
+## Process attribution
+
+Prefer `pidstat -u -r -d -p ALL 1 20` for the standard Linux process view.
+For receipts that retain PID birth identity, use the bundled collector:
+
+```sh
+python3 scripts/process-attribution.py --seconds 20 --output /disk/path/receipt.json
+```
+
+Run from the skill directory. Linux receipts contain raw one-second snapshots
+and CPU deltas ranked by busy cores, with process name, parent PID, birth ticks,
+RSS pages and unmatched boundary counts. They omit command arguments.
+
+Each row also reports `reapedChildCores`: CPU of children the process reaped
+during the interval, attributed to that parent. It shows which process ran
+commands too short-lived to appear in a snapshot, not the commands themselves,
+and can include CPU the children used before the interval started.
+
+Each interval reports `cpuBusyCores` per logical CPU for pinned runs (see
+[fenced-core arm](#fenced-core-arm)). Busy CPU excludes idle, iowait and steal
+time. A CPU brought online or offline during the interval reports `null`; the
+fenced-core gate rejects that interval.
+The collector uses its own `/proc/self/status` `VmHWM` for peak RSS;
+`ru_maxrss` can retain a launcher's inherited high-water mark.
+It records observer CPU and scan duration. Include those costs in the declared
+measurement budget; no negligible-impact claim follows from successful collection.
+
+On Windows, `scripts/process-attribution.ps1` accepts mandatory `OutputPath`
+and `StopPath` arguments. It saves process PID, start time, name and cumulative
+CPU, plus host activity and observer CPU/working set. Match PID and start time
+before computing deltas. It stops when the stop file exists or after 120 samples;
+choose a fresh stop path. Use the host's approved PowerShell invocation without
+changing execution policy.
+
+Neither collector stops jobs, takes a lock or grants admission. Boundary samples
+miss processes that start and exit between them; unreadable processes are counted
+as missing. CPU contributors explain observed activity, not whether it changed
+application latency. Keep host/resource gates and owner coordination separate.
+
+## Scheduling controls
+
+These Linux controls change resource allocation under competition; they do not
+establish isolation. Check support for the actual kernel, controller and I/O
+path. Record effective values and unavailable controls for every arm; requesting
+a setting does not prove it took effect.
+
+| Control                                                                          | Effect and limit                                                                                                                                                                                                             |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Nice level](https://man7.org/linux/man-pages/man2/nice.2.html)                  | Lower numeric values raise fair CPU scheduling priority. Permissions and autogroup policy affect the result. This does not reserve a core.                                                                                   |
+| CPU affinity (`taskset`)                                                         | Restricts available CPUs and can affect worker counts and parallelism. It does not reserve exclusive cores. Use it for a declared CPU configuration or a [fenced-core arm](#fenced-core-arm), not automatic noise reduction. |
+| [CPU and I/O cgroup weights](https://docs.kernel.org/admin-guide/cgroup-v2.html) | Adjust relative shares among active sibling groups. Parent limits and controller/device support still apply; a higher weight is not a capacity guarantee.                                                                    |
+| [Process I/O priority](https://man7.org/linux/man-pages/man2/ioprio_set.2.html)  | Depends on the supporting I/O scheduler and path. Process-specific priority does not cover asynchronous writes.                                                                                                              |
+| [Memory protection](https://docs.kernel.org/admin-guide/cgroup-v2.html)          | `memory.low` and `memory.min` protect against reclaim, not memory-bandwidth competition. Excessive hard protection can cause OOM. Memory caps remain limits, not reservations.                                               |
+
+### Fenced-core arm
+
+On a shared host where brief bursts from other sessions keep failing host-wide
+admission, a fenced-core arm keeps other work off chosen CPUs for a finite phase. It is a
+declared sensitivity arm that needs the user's authorization, because it changes
+other sessions' CPU placement:
+
+1. Choose the benchmark CPUs as whole physical cores (include SMT siblings) and pin
+   every arm, its browser or runtime and its children to them.
+2. Move every other thread you are permitted to change off the benchmark CPUs.
+   Record each thread's identity (PID, thread ID, birth ticks) and original
+   affinity. Stop and signal nothing. A thread that sets its own affinity, or
+   is created with an explicit mask, can stay eligible on the benchmark CPUs;
+   the gate still counts its CPU.
+3. Gate on foreign CPU on the benchmark CPUs: their busy time (`cpuBusyCores`)
+   minus the interval CPU of the benchmark's own live processes (`busyCores`).
+   Do not subtract `reapedChildCores`: it can include CPU used before the
+   interval, so it would understate foreign load. Process CPU is not per-CPU,
+   so the subtraction holds only while the whole tree stays on the benchmark
+   CPUs: check every thread's effective affinity at the start and end of each
+   batch, and reject the batch if any ran elsewhere. Boundary checks miss a
+   thread that widens and restores its affinity within the batch; when the
+   workload can change its own affinity, confine the tree with a cpuset it
+   cannot widen. In the same census, record every other permitted thread
+   still eligible on the benchmark CPUs as unfenced. Report host-wide load as
+   context.
+4. At the phase boundary, restore recorded threads after checking their birth
+   ticks. Threads started during the window inherited the fence; give them the
+   CPU set they would otherwise have inherited, usually all CPUs. A still-fenced
+   thread can start another while you restore, so repeat the census until a
+   full pass finds no permitted thread left fenced; threads started after their
+   creator is restored inherit the restored set. Do not freeze processes to stop
+   thread creation. Run this cleanup even when the phase fails.
+
+Report results as constrained to the pinned setting with the effective
+affinities. Processes you cannot change (other users, system services) stay
+unfenced; record them. In a virtual machine, guest affinity does not reserve
+host cores; host activity, shared cache, memory bandwidth and power limits
+still apply.
+
+Avoid realtime [CPU](https://man7.org/linux/man-pages/man7/sched.7.html) or
+[I/O](https://man7.org/linux/man-pages/man1/ionice.1.html) classes for generic
+benchmark noise reduction; they can starve dependencies or monitoring.
+Preserve the host's scheduling policy unless it authorizes a different regime.
+
+## Profiling and debugging
+
+Use a separate diagnostic run; instrumentation changes the work it observes.
+
+| Question                                    | Tool and reason                                                                                                                                                                                                                                       | Limits to record                                                                                                                          |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Where does JavaScript CPU time go?          | Runtime CPU profiler: [Node](https://nodejs.org/api/cli.html#--cpu-prof) or [Bun](https://bun.com/docs/project/benchmarking#cpu-profiling).                                                                                                           | Match runtime/version and profile settings. Samples locate hotspots; verify improvements with unprofiled runs.                            |
+| Which JS objects are allocated or retained? | Runtime allocation profiles and heap snapshots: [Node](https://nodejs.org/api/cli.html#--heap-prof), [Bun](https://bun.com/docs/project/benchmarking#heap-profiling).                                                                                 | Matching flags do not guarantee matching metrics; see the distinction below.                                                              |
+| Where does native/kernel CPU work go?       | Linux [perf stat](https://github.com/torvalds/linux/blob/master/tools/perf/Documentation/perf-stat.txt) and [perf record](https://github.com/torvalds/linux/blob/master/tools/perf/Documentation/perf-record.txt): counters, samples and call graphs. | Permissions, hardware/kernel support, symbols and stack unwinding affect evidence. Frame-pointer unwinding needs compatible binaries.     |
+| Which system calls fail or wait?            | Linux [strace](https://github.com/strace/strace/blob/master/doc/strace.1.in): syscall results, errors and ordering.                                                                                                                                   | Interception changes execution; summaries are not ordinary throughput. Traces may contain sensitive paths or payloads.                    |
+| Which native allocations churn?             | Linux [heaptrack](https://github.com/KDE/heaptrack): allocation counts, temporary allocations and allocation stacks.                                                                                                                                  | Symbols improve attribution. Pool allocators need annotations; native allocation traces do not identify individual GC-managed JS objects. |
+
+Node `--heap-prof` samples allocation activity. Bun's documentation describes
+a full V8-format heap snapshot at exit, not the same sampled allocation history;
+its accepted interval flag does not add allocation sampling. Record which kind
+of artifact was captured and verify semantics for the version used.
+
+For a concrete crash, hang or event-tracing question, use the available
+[debugger](https://www.sourceware.org/gdb/documentation/) or
+[system tracing tool](https://bpftrace.org/docs). They are optional diagnostic
+tools, not benchmark prerequisites; platform and permissions affect availability.
+
+For TypeScript compiler versus application timing, read [the language reference](javascript.md).
+
+## Correctness and audit evidence
+
+Use the repository's lint, type checks, focused tests and relevant static or
+security analysis. These establish intended behavior and detect defects; passing
+them does not establish speed or memory use. State their coverage limits.
+
+Add a tool after using it successfully on a real task. Record the question it
+answered, why it helped, its platform and measurement limits, and the official
+documentation. Keep untried candidates in research notes until then.

package/skills/hr-benchmarking/scripts/process-attribution.ps1

@@ -0,0 +1,20 @@
+param([Parameter(Mandatory=$true)][string]$OutputPath,[Parameter(Mandatory=$true)][string]$StopPath)
+$ErrorActionPreference='Stop'
+$cpuCounter=New-Object System.Diagnostics.PerformanceCounter('Processor','% Processor Time','_Total')
+$memoryCounter=New-Object System.Diagnostics.PerformanceCounter('Memory','Available MBytes')
+$pageCounter=New-Object System.Diagnostics.PerformanceCounter('Memory','Pages Input/sec')
+$records=@()
+try {
+  [void]$cpuCounter.NextValue()
+  for($i=0;$i -lt 120;$i++) {
+    $items=@(); $missing=0
+    foreach($p in Get-Process) {
+      try { if($null -ne $p.CPU) { $items+=@{pid=$p.Id;name=$p.ProcessName;cpuSeconds=$p.CPU;started=$p.StartTime.ToUniversalTime().ToString('o')} } } catch { $missing++ }
+    }
+    $self=Get-Process -Id $PID
+    $records+=@{utc=[DateTime]::UtcNow.ToString('o');totalCpuPercent=$cpuCounter.NextValue();availableBytes=$memoryCounter.NextValue()*1MB;pagesInputPerSec=$pageCounter.NextValue();processes=$items;missingProcesses=$missing;observerCpuSeconds=$self.CPU;observerWorkingSet=$self.WorkingSet64}
+    if(Test-Path $StopPath) { break }
+    [Threading.Thread]::Sleep(1000)
+  }
+  ConvertTo-Json -InputObject $records -Depth 5 -Compress | Set-Content -LiteralPath $OutputPath -Encoding utf8
+} finally { $cpuCounter.Dispose();$memoryCounter.Dispose();$pageCounter.Dispose() }

package/skills/hr-benchmarking/scripts/process-attribution.py

@@ -0,0 +1,107 @@
+"""Finite Linux CPU attribution; does not acquire admission, stop processes or print argv."""
+import argparse
+import json
+import os
+from pathlib import Path
+import resource
+import time
+from datetime import datetime, timezone
+
+
+def read_process(stat):
+    end = stat.rfind(")")
+    fields = stat[end + 2:].split()
+    return {"name": stat[stat.find("(") + 1:end], "parentPid": int(fields[1]),
+            "cpuTicks": int(fields[11]) + int(fields[12]),
+            "reapedChildCpuTicks": int(fields[13]) + int(fields[14]), "birthTicks": fields[19],
+            "rssPages": int(fields[21])}
+
+
+def snapshot(proc=Path("/proc")):
+    processes = {}
+    missing = 0
+    started = time.monotonic()
+    for path in proc.iterdir():
+        if not path.name.isdigit():
+            continue
+        try:
+            processes[int(path.name)] = read_process((path / "stat").read_text(encoding="utf-8", errors="replace"))
+        except (OSError, ValueError, IndexError):
+            missing += 1
+    cpu_lines = [line.split() for line in (proc / "stat").read_text().splitlines() if line.startswith("cpu")]
+    ticks = list(map(int, cpu_lines[0][1:9]))
+    per_cpu = {line[0][3:]: list(map(int, line[1:9])) for line in cpu_lines[1:]}
+    peak = int(next(line for line in (proc / "self/status").read_text().splitlines()
+                    if line.startswith("VmHWM:")).split()[1]) * 1024
+    usage = resource.getrusage(resource.RUSAGE_SELF)
+    return {"monotonic": time.monotonic(), "utc": datetime.now(timezone.utc).isoformat(),
+            # Busy excludes idle, iowait and steal: steal is time the hypervisor ran
+            # something else, not work by any guest thread.
+            "hostBusyTicks": sum(ticks) - ticks[3] - ticks[4] - ticks[7],
+            "cpuBusyTicks": {cpu: sum(t) - t[3] - t[4] - t[7] for cpu, t in per_cpu.items()},
+            "processes": processes,
+            "missingProcesses": missing, "scanSeconds": time.monotonic() - started,
+            "observerCpuSeconds": usage.ru_utime + usage.ru_stime,
+            "observerPeakRssBytes": peak}
+
+
+def cpu_busy_cores(before, after, scale):
+    # A CPU brought online or offline between snapshots has no interval value;
+    # report it as None so a gate cannot read it as idle.
+    return {cpu: (after[cpu] - before[cpu]) / scale if cpu in before and cpu in after else None
+            for cpu in sorted(before.keys() | after.keys(), key=int)}
+
+
+def compare(before, after, hz):
+    seconds = after["monotonic"] - before["monotonic"]
+    rows = []
+    prior = before["processes"]
+    current = after["processes"]
+    matched = set()
+    for pid, process in current.items():
+        old = prior.get(pid)
+        if old is None or old["birthTicks"] != process["birthTicks"]:
+            continue
+        matched.add(pid)
+        cpu = process["cpuTicks"] - old["cpuTicks"]
+        # When the parent reaps children, their total CPU is added to its
+        # cutime/cstime. The delta attributes that CPU to the parent; it can
+        # include CPU the children used before the interval started.
+        reaped = process.get("reapedChildCpuTicks", 0) - old.get("reapedChildCpuTicks", 0)
+        if cpu > 0 or reaped > 0:
+            rows.append({"pid": pid, **process, "busyCores": cpu / hz / seconds,
+                         "reapedChildCores": reaped / hz / seconds})
+    return {"startUtc": before["utc"], "endUtc": after["utc"], "seconds": seconds,
+            "hostBusyCores": (after["hostBusyTicks"] - before["hostBusyTicks"]) / hz / seconds,
+            "cpuBusyCores": cpu_busy_cores(before.get("cpuBusyTicks", {}), after.get("cpuBusyTicks", {}),
+                                           hz * seconds),
+            "unmatchedBefore": len(prior) - len(matched),
+            "unmatchedAfter": len(current) - len(matched),
+            "processCpu": sorted(rows, key=lambda row: -row["busyCores"])}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--seconds", type=int, default=20)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    if not 1 <= args.seconds <= 300:
+        parser.error("seconds must be between 1 and 300")
+    hz = os.sysconf("SC_CLK_TCK")
+    samples = [snapshot()]
+    for _ in range(args.seconds):
+        time.sleep(1)
+        samples.append(snapshot())
+    intervals = [compare(a, b, hz) for a, b in zip(samples, samples[1:])]
+    result = {"version": 2, "observerPid": os.getpid(), "clockTicksPerSecond": hz,
+              "bootId": Path("/proc/sys/kernel/random/boot_id").read_text().strip(),
+              "samples": samples, "intervals": intervals,
+              "limits": "Snapshots miss processes that start and exit between samples. reapedChildCores attributes children's CPU to the parent in the interval it reaps them, including CPU they used before the interval. Busy CPU excludes idle, iowait and steal. CPU attribution does not prove interference or grant admission. Observer overhead is included; no negligible-impact claim."}
+    args.output.write_text(json.dumps(result, indent=2))
+    print(json.dumps({"output": str(args.output), "intervals": len(intervals),
+                      "peakHostBusyCores": max(row["hostBusyCores"] for row in intervals),
+                      "observerPeakRssBytes": samples[-1]["observerPeakRssBytes"]}))
+
+
+if __name__ == "__main__":
+    main()

package/skills/hr-better-accessibility/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jakub Krehel
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-better-accessibility/NOTICE.md

@@ -0,0 +1,46 @@
+# Source notices
+
+This notice accompanies the hr-better-accessibility bundle when copied on its own.
+
+## jakubkrehel/skills
+
+Source: https://github.com/jakubkrehel/skills (compared at revision `267330e1adfc66a718fb65fa6918c1f06d0a689e`)
+
+- `skills/hr-better-accessibility/`, `skills/hr-better-colors/`, `skills/hr-better-layout/`,
+  `skills/hr-better-typography/` and `skills/hr-better-writing/`: adapted skill bundles,
+  including their supporting references and discovery metadata.
+
+Copyright (c) 2026 Jakub Krehel
+
+## emilkowalski/skills
+
+Source: https://github.com/emilkowalski/skills (compared at revision `e8a175de22ae1e49370fc144c1f3bb9aeedf988d`)
+
+- `skills/hr-better-accessibility/` and `skills/hr-better-layout/`: mobile behavior and
+  viewport guidance adapted from `skills/mobile-native/SKILL.md`.
+
+Copyright (c) 2026 Emil Kowalski
+
+## house-rules and MIT permission notice
+
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-better-accessibility/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: hr-better-accessibility
+description: "Accessibility rules for web UI: native elements, keyboard and focus, form labels and errors, accessible names, live regions, reduced motion, zoom and reflow. Use when building or reviewing web markup, forms, dialogs or interactive controls."
+license: MIT
+metadata:
+  upstream: https://github.com/jakubkrehel/skills
+  upstream_ref: 267330e1adfc66a718fb65fa6918c1f06d0a689e
+  upstream_path: skills/better-accessibility/
+  local_patches: "Use-when description; reduced-motion kill switch spares spinners; 320px reflow keeps the 2D-content exception; carousel pan-y, touch-callout and real-hardware check (from emilkowalski/skills mobile-native)"
+  house_rules_patches: "Portable provenance and review verdict"
+  mobile_native_source: https://github.com/emilkowalski/skills/blob/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills/mobile-native/SKILL.md
+---
+
+# Accessibility
+
+Most accessibility is free if you use the platform. Native elements ship with keyboard support, real labels announce themselves and a visible focus ring is one CSS rule.
+
+Write every fix in the project's styling system, and use the exact values below rather than familiar-looking substitutes.
+
+Reviewing means two walks. Keyboard-only, where every flow completes without a mouse. Then screen-reader, where every control announces a name, a role and its state. When unsure, take the platform default over a custom rebuild, and remove ARIA rather than add it.
+
+Contrast measurement and color fixes belong to `hr-better-colors`. Text sizing and iOS input zoom belong to `hr-better-typography`. Spatial RTL layout belongs to `hr-better-layout`.
+
+## Native elements first
+
+The first rule of ARIA: don't use ARIA when a native element exists. `<button>` for actions, `<a href>` for navigation, never `<div onClick>`. A real link must support Cmd/Ctrl/middle-click. No ARIA is better than bad ARIA. See [semantics-and-aria.md](semantics-and-aria.md) for landmarks, button-vs-link and disabled states.
+
+## Visible focus rings
+
+Style `:focus-visible`, not bare `:focus`. Keyboard users get a ring and mouse users usually don't. Prefer the browser's unmodified indicator.
+
+A custom ring needs a project focus token or another explicit color. Verify the whole indicator against every adjacent color it crosses, `currentColor` included. Use at least a `2px` solid perimeter or an equivalent visible area. Never use `outline: none` without a verified replacement, and preserve system colors in forced-colors mode. Recipes are in [focus-and-keyboard.md](focus-and-keyboard.md).
+
+## Full keyboard support
+
+Every pointer interaction needs a keyboard path. Follow the ARIA APG patterns: Escape closes overlays, arrow keys move within composite widgets, Tab moves between widgets, Enter and Space activate.
+
+Use only `tabindex="0"` to join the natural tab order and `tabindex="-1"` for programmatic focus. Positive values break that order. Composite widgets use roving tabindex, where the active item is `0` and every other is `-1`.
+
+## Trap and restore focus
+
+Modals set `inert` on the background content, move focus inside on open and return focus to the trigger on close. Add `overscroll-behavior: contain` so background content doesn't scroll.
+
+## Minimum hit area
+
+WCAG 2.5.8's Level AA baseline is a 24×24 CSS-pixel target, or one of its spacing, equivalent-control, inline, user-agent and essential exceptions. Aim for 44×44px on touch and 40×40px on desktop where density permits. Extend with a pseudo-element when the visible element should stay smaller.
+
+Never let extended hit areas overlap. Give decorative layers `pointer-events: none`, so a glow never swallows the clicks meant for the control beneath it. Sizes and collision rules are in [hit-areas.md](hit-areas.md).
+
+## Label and type every control
+
+Every input gets a `<label for>` or a wrapping `<label>`. A placeholder is never a label. Label and control share one hit target, with no dead zone between a checkbox and its text.
+
+Add `autocomplete` with a meaningful `name`, plus the `type` and `inputmode` that summon the right keyboard. Never block paste; users paste passwords and one-time codes. See [forms.md](forms.md).
+
+## Errors that announce
+
+Keep submit enabled until the request starts, then disable with a spinner and the original label. Validate on submit. Mark failing fields `aria-invalid="true"`, point `aria-describedby` at the inline error text and focus the first invalid field.
+
+Use native `disabled` when a control is genuinely unavailable. Reach for `aria-disabled="true"` only when it should stay focusable, then block pointer, keyboard and form behavior in code and style the state explicitly.
+
+## Accessible names everywhere
+
+Icon-only buttons need a descriptive `aria-label`. Visible label text must appear in the accessible name. Decorative elements get `aria-hidden="true"`, never on a focusable element.
+
+## Don't rely on color alone
+
+Status needs a redundant cue: an icon, text, or an underline alongside the color. Work out which WCAG contrast requirement applies, then use `hr-better-colors` to measure the rendered pair. When it fails, report the pair and the requirement it misses, and leave the colors alone unless asked.
+
+## Honor prefers-reduced-motion
+
+Wrap motion in `@media (prefers-reduced-motion: no-preference)` so it is opt-in. Under reduced motion, replace slides and scales with opacity crossfades, and kill parallax and autoplay entirely.
+
+Two rules hold regardless of the preference. Autoplaying media needs a visible pause control, and toasts carrying an action or an error stay until dismissed. See [motion-and-zoom.md](motion-and-zoom.md).
+
+## Announce dynamic content
+
+Three mechanisms, three jobs. `aria-describedby` carries field-specific validation. A polite live region (`role="status"`) carries non-urgent updates not tied to a control, such as toasts and result counts. `role="alert"` carries urgent untied errors and nothing else.
+
+Repeated polite announcements need a stable empty region rendered before its text updates. Dynamically inserted alerts vary in support, so test them on the screen readers you target. See [screen-readers.md](screen-readers.md).
+
+## Alt text by purpose
+
+Decorative images get `alt=""`. Informative images describe the meaning. Functional images describe the action: a search icon button is `alt="Search"`, not `alt="magnifying glass"`.
+
+## Structure is navigation
+
+Use headings that describe their sections and form a coherent outline. Give the page one `<h1>` and nest the levels below it without skipping. Expose one visible primary `<main>` landmark. When repeated navigation or chrome precedes it, make a "Skip to content" link the first focusable element. Anchored headings get `scroll-margin-top`.
+
+## Survive zoom and text resize
+
+The page must work at 200% zoom and reflow at 320px width without horizontal scrolling. Tables, maps and code blocks may scroll inside their own container. Use `min-height` rather than fixed `height` on text containers. Prefer `rem` breakpoints where they fit the codebase, and never let the viewport meta cap how far the reader can zoom.
+
+## Before you finish
+
+| Mistake                                         | Fix                                                              |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| Custom focus color assumed to work everywhere   | Verify it against every adjacent color and in forced-colors mode |
+| Repeated polite update inconsistently announced | Keep a stable empty status region and update its text            |
+| `assertive` live region for a routine toast     | Use `polite`; reserve `assertive` for errors                     |
+| `aria-hidden="true"` on a focusable element     | Remove it or make the element non-focusable                      |
+| Submit disabled until the form is valid         | Keep it enabled; validate on submit and focus the first error    |
+| Hover treatment stuck after a tap on touch      | Gate hover styling with `@media (hover: hover)`                  |
+| Tooltip on a natively `disabled` control        | Text beside it, or `aria-disabled` so it stays focusable         |
+
+## Reporting
+
+**Severity.** `HIGH` prevents a task, hides content from assistive technology, or creates a systemic failure. `MEDIUM` makes an interaction meaningfully harder. `LOW` is isolated polish.
+
+**Verification.** Without a browser: accessible names on every interactive element, keyboard handlers on non-native controls, focus styles, `prefers-reduced-motion` guards and form labels bound to their inputs. With one: tab the flow in order, read computed names and roles from the accessibility tree, confirm a visible focus indicator at every stop and run an automated audit. Report every check you could not run as `Not verified`.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| -------- | -------- | ------ | ----- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+Report `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable accessibility findings" and report verification.

package/skills/hr-better-accessibility/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Better Accessibility"
+  short_description: "Focus, keyboard, ARIA, forms and screen readers"