# Leonid Svyatov: all posts > I'm Leonid, a software engineer. For 15+ years, I've worked with founders to figure out what they need, build it, and keep it running. I like asking questions before writing code and helping other developers grow. These days, I build with coding agents and share much of my work as open source. ## Omarchy on a Late 2015 iMac 5K: Fixing the Login Loop - URL: https://svyatov.com/blog/omarchy-on-a-late-2015-imac-5k-fixing-the-login-loop/ - Date: 2026-10-21 - Tags: linux, omarchy, tutorial, debugging [Apple’s official macOS support for this model stops at Monterey](https://support.apple.com/en-us/108054). [Omarchy](https://omarchy.org/) literally gave my iMac a second life. Credit to DHH and the team for making old hardware useful again with a modern Linux desktop. Getting there required one workaround. My fresh Omarchy installation accepted my password, waited, then returned to the login screen. It had never reached the desktop. Here is what worked. ## Hardware and symptoms My configuration: - **Model:** iMac17,1, 27-inch Retina 5K, Late 2015 - **GPU:** Radeon R9 M395 / M395X Mac Edition, using `amdgpu` - **Omarchy:** 4.0.5-1 The machine appeared to reboot after login, but neither the Apple logo nor the Limine boot menu reappeared. It was returning to the graphical login screen. Pressing **Ctrl + Option + F3** opened a text console. You may also need **Fn** on an Apple keyboard. My username and password worked there. That established that the system had booted and my credentials were valid. ## Identify the failure From the text console, run these commands one at a time. Check the model and graphics driver: ```sh cat /sys/class/dmi/id/product_name ``` ```sh lspci -nnk -d ::03xx ``` Read the desktop startup log: ```sh journalctl --user -b -u 'wayland-wm@*' -u wayland-session-waitenv.service --no-pager -n 60 ``` Read the graphics-driver log: ```sh journalctl -b -k --grep='amdgpu|drm|GPU|ring|timeout' --no-pager -n 50 ``` My logs showed successful authentication, followed by Hyprland startup. UWSM then timed out waiting for `WAYLAND_DISPLAY` and `HYPRLAND_INSTANCE_SIGNATURE`. Systemd eventually killed Hyprland. The kernel repeatedly reported: ```text amdgpu 0000:01:00.0: last message was failed ret is 0 ``` These messages pointed toward the graphics driver. The successful test below strongly implicated GPU power management. ## Test the workaround for one boot 1. Reboot. At the **Limine** menu, select the normal Omarchy entry and press **E**. 2. Find the `cmdline:` line. Append a space followed by: ```text amdgpu.dpm=0 ``` Preserve the existing parameters. If `amdgpu.dpm` is already present, change its value instead of adding a duplicate. 3. Press **Ctrl + X** or **F10** to boot, then try logging in. This change lasts for one boot and does not modify the saved configuration. **With this single parameter, my desktop started.** The [AMD driver documentation](https://github.com/torvalds/linux/blob/master/drivers/gpu/drm/amd/amdgpu/amdgpu_drv.c) defines `dpm=0` as disabling dynamic power management. If your login still fails, return to the text console and check: ```sh cat /sys/module/amdgpu/parameters/dpm ``` Expected output: ```text 0 ``` If it shows `0` and the desktop still fails, this workaround has not solved your case. ## Make it persistent Only do this after the temporary test succeeds. 1. Open a dedicated boot-configuration file: ```sh sudoedit /etc/limine-entry-tool.d/imac-gpu.conf ``` 2. Add this line, preserving any existing content: ```sh KERNEL_CMDLINE[default]+=" amdgpu.dpm=0" ``` Save and close the editor. 3. Rebuild the boot configuration: ```sh sudo limine-mkinitcpio ``` Wait for the rebuild to finish successfully. If it reports errors, resolve them before rebooting. Omarchy uses this [additive configuration pattern for Apple hardware settings](https://github.com/omacom/omarchy/blob/94a8fbc2d67eec5673c7f16b8c5e8a9c8452ffdc/install/hardware/apple/fix-t2.sh#L35-L39). Reboot normally, without editing the Limine entry. Check that the desktop starts, then verify: ```sh cat /sys/module/amdgpu/parameters/dpm ``` It should print `0`. Saving the parameter this way kept login working across reboots on my iMac. ## Scope and rollback This was tested on the hardware and Omarchy version listed above. There is also a [related M395 report](https://github.com/omacom/omarchy/discussions/5151#discussioncomment-17789456). The broader discussion covers different GPUs, so do not copy every parameter from it. Disabling dynamic power management may affect performance and power consumption. The exact driver defect remains unconfirmed. This is a working workaround. To undo it, remove the added line from `/etc/limine-entry-tool.d/imac-gpu.conf`, run `sudo limine-mkinitcpio`, and reboot. --- ## Right model, right task: routing Claude Code across Opus, Sonnet, and Haiku - URL: https://svyatov.com/blog/right-model-right-task-routing-claude-code-across-opus-sonnet-and-haiku/ - Date: 2026-10-17 - Tags: ai, llm, productivity Most of your Opus context can disappear before any real thinking happens. It goes into reading files, into parsing agent transcripts, into tracking which of a hundred subagents finished and which one retried. By the time Opus gets to the actual hard problem, the one you brought Opus in for, it's carrying the weight of a thousand lines of boilerplate it never needed to touch. There's a better split. This is what it looks like. --- ## The core idea: let Opus write the script, then get out of the way You launch Claude Code like this: ```bash claude --model opus --effort ultracode ``` You're not asking Opus to run the whole show. You're asking it to do one specific thing: turn your objective into an executable workflow script. A JavaScript file that knows the work, holds the loop, and orchestrates everything else. Once that script exists, Opus steps back. The proposed design uses [Claude Haiku 5.5](https://www.anthropic.com/claude-haiku-5-5) for bounded-concurrency narrow file scans: fast, cheap reads that extract candidate locations without touching anything. It's reading, extracting candidates, flagging anything that looks wrong. The broader architecture questions need a more thorough look. Sonnet 5.5 handles the patching. Each fix gets its own isolated worktree. An independent reviewer agent and tests check the result before main-branch integration. The combined changes need verification too. Nothing touches the main branch until it's been confirmed. Then Opus comes back. It reads the verified findings and the unresolved cases, not every raw transcript. **Opus plans · Haiku scans · Sonnet ships.** --- ## The three moments Opus actually shows up This is the key shift in how the workflow is designed. Opus isn't absent. It appears at exactly three points: 1. **Before the run**: authoring the workflow script that defines how everything executes 2. **After the swarm finishes**: reading the verified findings and unresolved cases (not the raw transcripts, not the intermediate steps) 3. **Before anything ships to git**: signing off Everything in between goes to faster, cheaper models. And because the workflow script is explicit and rerunnable, you don't rewrite the plan on every run. Opus wrote the playbook once. The rest of the system follows it. Runtime still costs every time through, so the savings aren't automatic. --- ## What the full tree looks like Here's the execution flow: ```plaintext Opus 5.5 runs the main session and writes workflow.js └── pipeline() fans out bounded Haiku 5.5 file scans └── parallel() runs independent finding verifiers └── Sonnet 5.5 patches verified fixes in separate worktrees └── independent review and tests check patches and integration └── Opus 5.5 reviews results, including unresolved findings ``` [Claude Code dynamic workflows](https://code.claude.com/docs/en/workflows) are JavaScript scripts that orchestrate background agents using `pipeline()` and `parallel()` primitives. [Worktrees](https://code.claude.com/docs/en/worktrees) isolate working files, but they do not isolate all shared state, and integration can still conflict. JSON schema validation checks that output has the right shape; it does not verify that the content is factually correct. These per-stage model assignments aren't defaults, by the way. You have to request them explicitly. The script holds the loop so Opus doesn't have to. --- ## Jev and the micro-forks Deterministic branches (which file to read, which tool to call, how many retries before giving up) belong in plain JavaScript. You do not need a model for those; you need a condition. Jev is an optional probabilistic semantic classifier that routes among a fixed set of known options when the routing decision is genuinely ambiguous in natural language. The name comes from William Stanley Jevons, not from an acronym. TypeSafe describes the approach in [their System One introduction](https://typesafe.ai/blog/introducing-system-one-models-and-jev). Your application owns the thresholds (how confident Jev needs to be before routing) and the escalation policy (what happens when confidence falls below the threshold); those are documented in [the System One build guide](https://docs.typesafe.ai/concepts/how-to-build-with-system-one). Jev is not built into Claude Code workflows. Wiring it in means building a separate integration that your agents can call. It's the same principle one layer down. You're asking "which *moment* in this task needs a model at all?" Most of them don't. --- ## Why this maps to harness engineering This SDLC design is really just harness engineering applied to model orchestration. The harness controls what each model reads, what tools it can trigger, what data survives context resets, and when execution must halt. Andrej Karpathy's [model-as-CPU, context-as-RAM analogy](https://www.youtube.com/watch?v=zjkBMFhNj_g) is a practical framing: the model processes whatever you load into context, the same way a CPU works on whatever is in RAM. The useful implication is that orchestration state (counters, stage results, review outcomes) belongs outside the main context window, stored where it can be retrieved selectively rather than carried wholesale through every call. The workflow script is the operating system. CLAUDE.md carries the durable rules (every finding gets an independent verifier, fix loops stop after two rounds with no progress), but those are instructions to the model, not hard constraints. The script itself implements the verifier gate and the loop counters. The isolated worktrees are the separate processes. Sonnet doesn't need to know what Haiku found two files ago, any more than one process needs to read another process's stack, though cross-file dependencies do travel when summaries get passed between stages. Those [durable instructions are context, not enforced configuration](https://code.claude.com/docs/en/memory). You can wire this up directly from the prompt: > "Rebuild my Claude Code setup around this tree: > 1. Run the main session on Opus 5.5 with ultracode on > 2. In every workflow, run read-only scan stages on Haiku 5.5 and edit stages on Sonnet 5.5, each edit in its own isolated copy > 3. Add one rule to CLAUDE.md: every finding gets an independent verifier agent before it's reported, and fix loops stop after two rounds with no progress. Implement the counters, gates, and combined verification step in the script. > 4. Use plain JavaScript for all deterministic routing; consider a separately integrated Jev classifier only for decisions that are genuinely semantic, not for branching you can express as a condition. > Show me every change as a diff first, no edits until I say go" --- ## A note on speed and scope Independent benchmarks put Haiku 5.5 (Max) at [hundreds of output tokens per second](https://artificialanalysis.ai/models/claude-haiku-5-5). Output token speed does not tell you how long an audit run will actually take. Input size, tool-call wait times, bounded concurrency limits, and review round-trips all contribute to wall time, and they vary by codebase. The plan/scan/patch split described above is a proposed structure, not a benchmark result; your numbers will depend on your files, your models, and how many rounds reach the reviewer. One thing the rerunnable script does buy you: when something fails mid-run, you fix the failure and re-run the script rather than rewrite the orchestration. It does not guarantee lower total token use or lower cost. Splitting work across three model tiers can raise total consumption if scan and patch stages run many small calls. Budget for this before you commit to the architecture. --- ## What to do with this If you're running Claude Code today and pointing Opus at everything, try the split. Let Opus write the workflow, then deliberately remove it from the loop until verification is done. Before scaling it, test quality, missed cases, latency, and cost on a representative slice of your repo. The per-Opus-call context does get cleaner, but overall token usage and cost can still increase once you count the full pipeline, so measure on something real before you decide it's an improvement. A lot of what you were paying Opus to see didn't require Opus to see it. The work just needed somewhere to go. Build the harness, and it has somewhere to go. --- ## Handrail: write your guardrails once, enforce them everywhere - URL: https://svyatov.com/blog/handrail-write-your-guardrails-once-enforce-them-everywhere/ - Date: 2026-10-06 - Tags: ai, opensource, productivity You write a rule in Claude Code: never run `git push` without asking first. It fires every time, exactly as intended. Then you open Codex CLI for a different project. The rule doesn't exist there. So you crack open Codex's configuration, figure out its hook format (different from Claude Code's), and wire up the same rule again. Then oh-my-pi ships a new version, you add it to your workflow, and the whole cycle repeats. This is the problem nobody warned you about when AI coding agents got good: they each have their own hook system, their own event names, their own JSON schemas, and their own opinions about where config lives. Your guardrails are real: the problem is they only live in one place. I built [Handrail](https://github.com/svyatov/handrail) to fix that. ## The fragmentation problem, in concrete terms Claude Code has many lifecycle points you can [hook into](https://code.claude.com/docs/en/hooks). `PreToolUse` can block an action outright; exit code 2 blocks the tool call, not the entire agent. `PostToolUse` lets you validate or reformat after the fact. Configuration lives in `.claude/settings.json` (project-level configuration), and the hook system is genuinely powerful. Codex CLI has a similar set: `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, `Stop`, and more. Its hooks receive a JSON payload on stdin and communicate decisions back through stdout. It shares Claude-shaped hook groups and decision structures, though with differing event coverage, tool payloads, and supported decisions. Powerful, and structurally related but distinct. [See the docs](https://learn.chatgpt.com/docs/hooks). Oh-my-pi takes yet another approach. Its [extension system](https://github.com/can1357/oh-my-pi/blob/main/docs/extensions.md) is TypeScript-first: you define an `ExtensionFactory` that binds handlers to the runtime event bus with `api.on("tool_call", ...)`, and you return `{ block: true, reason: "..." }` to deny an action. Expressive, but nothing like the other two. If you use more than one of these, and I do, you end up maintaining three separate, increasingly divergent rule sets for what is essentially the same policy. "Don't force-push to main" shouldn't need to be written three times. ## What Handrail does One file per rule. One binary. Handrail reads the files and syncs native hooks into each harness. Those hooks invoke the Go engine to evaluate the shared rule files at event time. Handrail v0.5.1 or later must be installed to use all three adapters. You declare a rule once, in Handrail's neutral format, and then run: ```bash handrail sync --harness claude handrail sync --harness codex handrail sync --harness omp ``` Each `sync` installs hook entries for Claude and Codex (the full plugin packages are available separately), or an owned, profile-aware native extension for oh-my-pi. The agent sees its native hooks; Handrail handles the translation. One caveat on rules: as of v0.5.0, Codex ask rules degrade to warn. Matching calls can proceed without hook-enforced approval. Use block for actions that must be denied; sync and doctor will report which rules degrade. See the [changelog](https://github.com/svyatov/handrail/blob/main/CHANGELOG.md) for details. No third-party runtime sprawl, either. The binary has one third-party runtime dependency: `mvdan.cc/sh/v3/syntax`, a shell parser. A lint allow-list keeps it that way. The whole thing is a single binary you drop onto your machine. ## The rule format Handrail's rule format is harness-neutral. Canonical event names use Claude Code's vocabulary; payload fields and actions are normalized across harnesses. You describe what you want to happen (at which lifecycle point, under what conditions, with what consequence), and Handrail figures out the right native hook to install. Native capabilities differ by platform, but the format bridges them. The [spec](https://github.com/svyatov/handrail/blob/main/docs/spec.md) treats all input as potentially hostile. That's intentional. A prompt-injected agent produces every input a careless agent does and then some, so the rule engine assumes the worst. It's also upfront about the limits of this: hooks are best-effort, never a security boundary. Every harness has a documented way to disable its hooks (managed policies may restrict disabling of user-installed hooks), and Handrail detects the ones it can see rather than claiming to defend against all of them. I'd rather have that honesty in the spec than a false sense of coverage. ## Migrating from hookify If you started building rules with [hookify](https://github.com/anthropics/claude-code/tree/main/plugins/hookify), which is Claude Code's own plugin for this, you know it uses a nice lightweight format: markdown files with YAML frontmatter and regex patterns. It works, but it's written for Claude Code. Handrail can import what you already wrote: ```bash handrail import hookify ``` That converts your existing hookify rules into Handrail's neutral format, so you're not starting from scratch. The import skips unsupported fields, patterns, tool matchers, and ambiguous rules, and reports what it skipped. You keep the rules you've accumulated, but full portability to all harnesses isn't guaranteed immediately, especially with degraded features (Codex ask rules). ## The oh-my-pi adapter Oh-my-pi support shipped in [v0.5.1](https://github.com/svyatov/handrail/releases/tag/v0.5.1). The adapter is more involved than the Claude Code and Codex ones because oh-my-pi's extension system is natively TypeScript and structurally different. What landed: a binary-managed native extension that is profile-aware and delegates tool and lifecycle decisions to the existing Go engine. Native denial and approval work, once-only main-session Stop hooks work. The extension installs via `handrail sync --harness omp` and doesn't require a skill package or a separate bootstrap downloader; the binary manages it directly. Prompt submission and child-stop denial are unsupported. ## Performance The Go engine targets single-digit milliseconds end-to-end for each hook event. That covers the full round-trip: receive the event, evaluate every applicable rule, log or act on any that match, return a decision. Linux CI's [timing tests](https://github.com/svyatov/handrail/blob/main/main_test.go) fail when the median exceeds 20ms in three representative Claude adapter scenarios: no-match PreToolUse, matching-and-logging PreToolUse, and SessionStart with rule examples. macOS skips the timing test. I care about this because hooks that add noticeable latency to every agent action get disabled. A guardrail that's switched off because it made the agent feel sluggish isn't protecting anything. ## Where things stand Handrail is at v0.5.1, pre-1.0, and the public surface (command set, rule file format, exit codes) is stable enough that I've documented it formally in the spec. The current versioning policy: a minor bump may break you, a patch bump will not. I'll also keep at least one deprecation release before removing anything, so you'll see a warning with the replacement name before anything disappears. If you use Claude Code, Codex, or oh-my-pi, or any combination of them, and you've ever found yourself copy-pasting the same policy into a third config file, Handrail is for you. The repo is at [github.com/svyatov/handrail](https://github.com/svyatov/handrail), and the docs include a quick-start, the full rule format reference, and the spec. Write the rule once. Let Handrail handle the rest. --- ## Three agentic skills I wish I'd started using sooner - URL: https://svyatov.com/blog/three-agentic-skills-i-wish-id-started-using-sooner/ - Date: 2026-09-26 - Tags: ai, productivity, testing Your test suite takes five minutes to run. You know at least half of those tests are not pulling their weight. And yet, you never fix it, because fixing it isn't the work – it's the meta-work, the thing you do after the real thing. That's exactly why I built two of these skills myself and adopted the third. Two of them – improve-tests and debrief-skill – live in my [agent-toolkit](https://github.com/svyatov/agent-toolkit), right next to two dozen other plugins. It's MIT-licensed, so fork it, tweak it to fit your own setup, or send a contribution back. The third one – retro – lives in [SuperMatt](https://github.com/svyatov/supermatt), my take on [Matt Pocock's skills](https://github.com/mattpocock/skills) that turns them into one self-checking flow for Claude Code and Codex, from idea to reviewed code. If retro resonates with you, give the rest of the flow a try. ## improve-tests: because agents run tests constantly, and slow tests compound The idea behind [improve-tests](https://github.com/svyatov/agent-toolkit/blob/main/plugins/improve-tests/skills/improve-tests/SKILL.md) is simple: measure first, then cut. The skill profiles your test suite, identifies which tests cost the most time while catching the least, and then actually fixes them. Slow setup, redundant assertions, tests that can never fail – gone. I ran it across three projects. The results were not subtle. A client's Rails app went from 319 seconds wall time down to 41-72 seconds. That's a 4-8x speedup. Single files saw even sharper drops – the PDF spec fell from 98 seconds to 13, the anonymization spec from 110 seconds to 9. `ouroboros`, a Bun project, went from 221 seconds to about 83, a 62% reduction. The slowest file alone (which was taking 180 seconds) came down to 40. In total, about 140 tests were removed across all three projects. No lost coverage was reported. There was also a bonus: the skill found a real bug. A row-lock waiter in `ouroboros` was giving up silently, so one concurrency test was claiming to prove something it was never actually verifying. Three flaky tests were fixed as well – one had been failing 47 out of 90 runs and came down to zero. That last part matters. The skill doesn't just delete tests to hit a faster number. It checks that whatever stays can actually catch a real break. ## debrief-skill: your skills, but better, automatically [debrief-skill](https://github.com/svyatov/agent-toolkit/blob/main/plugins/debrief-skill/skills/debrief-skill/SKILL.md) is the one I find hardest to explain, and also the one I'd be most reluctant to give up. After any skill runs, you point debrief-skill at it. It reads through the whole session transcript, finds every piece of friction – errors, retries, confusing steps, dead ends – and traces each one back to a specific line in the skill definition that caused it. Then it proposes a fix. The part that makes this interesting: it works on itself, too. The debrief-skill has been improved by running debrief-skill on debrief-skill sessions. It's a self-reinforcing loop, and it means your whole toolkit quietly gets better over time without you having to sit down and audit it manually. It's read-only by default, so nothing changes without your approval. But the proposals are usually specific enough that approving them takes seconds. ## retro: because the code isn't always the problem [retro](https://github.com/svyatov/supermatt/blob/main/skills/retro/SKILL.md) runs after an implementation phase and looks at something different: not the code you wrote, but the environment you wrote it in. It reads the Claude Code session files directly from disk, finds friction in the tooling and instructions, and suggests what to change for next time. Where debrief-skill improves skills, retro improves everything around them. The prompts, the setup, the configuration. The stuff that's easy to blame on a bad day rather than fix properly. You can run it after any phase, really. I've started running it more liberally than just post-implementation. ## Why I regret not starting sooner The honest answer is that all three of these hit the same category of problem: maintenance work that's real and important and always loses to whatever is urgent right now. Slow tests? You know they're slow. You'll fix them eventually. Friction in a skill? You'll remember it next time. Tooling that's slightly off? Good enough. The skills make the "eventually" automatic. They close the loop that otherwise just stays open. If you're doing a lot of agentic work – and at this point, who isn't – these three are worth adding to your rotation. The compounding effect of debrief-skill and retro especially: the improvements stack, and six months from now you'll be working with a toolkit that's substantially sharper than what you started with. The version of me from a year ago would have appreciated the nudge ;) --- ## ArchSpec: when your AI agent doesn't know your rules, make the rules unbreakable - URL: https://svyatov.com/blog/archspec-when-your-ai-agent-doesnt-know-your-rules/ - Date: 2026-09-23 - Tags: ruby, rails, ai, architecture A thing is happening in Rails shops everywhere right now: AI coding assistants are writing large chunks of production code. Cursor. Claude. Copilot. Whatever your team has adopted, the output is real and it's landing in your codebase at a pace that code review alone can't fully absorb. These tools are genuinely good at writing Ruby. They understand Rails conventions pretty well. They don't understand *your* conventions – the ones that live in your CONTRIBUTING.md, your team wiki, and the collective memory of however many sprint retrospectives you've sat through. [ArchSpec](https://archspecrb.dev/) is the most direct answer I've found to this problem. ## The idea: executable architecture The insight behind ArchSpec is deceptively simple. Your architecture already has rules. The rules just aren't enforced. So enforce them. You write your conventions in a file called `Archspec.rb`: ```ruby architecture :rails controllers.cannot_use :helpers, :mailers, :jobs models.cannot_use :controllers services.cannot_call :render, :redirect_to jobs.cannot_reference_constants "Current" ``` Then you add `bundle exec archspec check` to your CI pipeline. A PR that violates those rules fails. It doesn't matter who wrote the code – a senior engineer, a new hire, or a model with no memory of your last architecture discussion. That last part is the point. ## What you can actually enforce The built-in `architecture :rails` preset handles the most common Rails boundary violations: models reaching into controllers, services calling `render`, that kind of thing. The custom component system is the interesting part: ```ruby component :queries, in: "app/queries/**/*.rb" queries.cannot_call :save!, :update!, :destroy! component :commands, in: "app/commands/**/*.rb" commands.must_implement :call component :services, in: "app/services/**/*.rb" services.must_be_empty because: "rich model" ``` You're not limited to Rails defaults. If your app has a command pattern, a query layer, or any other structural convention, you can encode it here. The `must_implement` check is particularly useful – it's a contract that every class in that layer exposes the right interface. The `jobs.cannot_reference_constants "Current"` rule deserves a specific callout. It catches a real bug class: `CurrentAttributes` data set during a web request is not available in background jobs. ArchSpec can enforce this statically, before the bug surfaces at 2am in a production log. ## Fast by design ArchSpec indexes Ruby source with [Rubydex](https://github.com/Shopify/rubydex) and [Prism](https://github.com/ruby/prism), and reads constant names from your class and module declarations. It never boots your application. This matters: the feedback loop for architecture violations should be as short as possible, and a linter that takes 45 seconds to start defeats its own purpose. ## The error output is CI-ready ```plaintext [error] services must not call #render [methods.forbid] app/services/create_user.rb:7:5 6 │ def call → 7 │ render :new │ ^~~~~~~~~~~ 8 │ end note: CreateUser calls render 1 architecture violation found. ``` Clear enough for a developer to act on immediately. Clear enough for a CI log that you're skimming at 11pm. That's the bar good static analysis output should clear. ## Getting it running takes five minutes ```ruby # Gemfile group :development, :test do gem "archspec" end ``` ```bash bundle install bundle exec archspec init bundle exec archspec check ``` `archspec init` creates a starter `Archspec.rb` with `architecture :rails`. From there, you add your custom rules incrementally. Start with the violations that have burned you before. The gem is at v1.1.0, requires Ruby 3.2+, and is MIT licensed. ## The bigger shift We spent the last decade building tools to catch code quality issues automatically – RuboCop, Brakeman, database linters. Architecture was the one thing that stayed manual, enforced through review and culture and the occasional frustrated comment in a PR. AI agents have accelerated the cost of that gap. If a single assistant can generate a week's worth of code in a day, the architectural drift that used to accumulate over months can now happen in an afternoon. ArchSpec isn't a complete answer to this. It's the right kind of answer: make the rules explicit, make them executable, and let the machine enforce them so you don't have to. --- ## Agent shortcuts: aliases for your AI coding agent - URL: https://svyatov.com/blog/agent-shortcuts-aliases-for-your-ai-coding-agent/ - Date: 2026-09-22 - Tags: ai, productivity, git I have 100+ shell aliases in my [dotfiles](https://github.com/svyatov/dotfiles). `ai` for `claude`. `cx` for `codex`. `be` for `bundle exec`. You get the idea. After 15 years at the terminal, typing the full command feels almost rude. When I started using Claude Code, it took me about a week before I felt the same itch. The agent is great at what it does, but asking it to "commit everything, make a good conventional commit message, scan for secrets first, don't commit on main" every single time gets old fast. I added slash commands in Claude Code. Problem solved – for Claude Code. Then I started using Codex too. Back to square one. Yesterday I finally fixed this properly. I moved all my agent shortcuts into a `shortcuts` plugin in my [agent-toolkit](https://github.com/svyatov/agent-toolkit), where they work across Claude Code and Codex both. ## Why shortcuts matter more than you'd think Repeating a workflow by voice or text gets old when you could select a named command instead. The same is true with agents. Invoking `/cpr` takes less effort than spelling out "commit, push, and open a pull request", and gives the agent the same written workflow every time. That consistency is the underrated part. When you invoke `/cb`, the instructions tell the agent to read the full diff, scan for credentials, create a branch if you're on the default branch, prefer explicit staging paths, write a conventional commit message that matches your log's existing style, and commit. No need to repeat qualifiers like "but don't commit on main" or "check for secrets first": those are already written down. `/c` deliberately stays on your current branch, including main. These are instructions for an agent, so they make the workflow explicit without guaranteeing identical results. Think of them as microskills. Each one is a tiny, named unit of knowledge you can invoke on demand. The shortcuts disable automatic invocation in both hosts. Their full instructions load when used. Context costs still differ: Claude Code excludes these manual-only skills' descriptions until invocation, while Codex documents loading skill metadata up front. The benefit is keeping the full workflow out of the initial context, not a universal promise of zero overhead. ## The shortcuts Here's what's in the plugin. I've grouped them by the workflow phase they belong to. ### Committing | Command | What it does | | --- | --- | | [/c](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/c/SKILL.md) | Commit all changes on the current branch. Main included if that's where you are. Scans for credentials before staging or committing. | | [/cb](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/cb/SKILL.md) | Same as /c, but if you're on the default branch, creates a new branch first with a sensible type/kebab-description name. This is the one I use 80% of the time. | | [/cp](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/cp/SKILL.md) | Commit, then push. | | [/cbp](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/cbp/SKILL.md) | Commit (branching off the default branch first if needed), then push. | ### The full loop | Command | What it does | | --- | --- | | [/cpr](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/cpr/SKILL.md) | Commit, push, and open a pull request, or reuse the branch's existing PR. Creates a branch first if you're on the default branch. Uses a conventional commit title. | | [/cprw](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/cprw/SKILL.md) | Commit, push, open a PR, wait for CI to pass, and squash merge. Creates a branch first if you're on the default branch. Stops on failed checks; repository protections still apply. | ### Git operations | Command | What it does | | --- | --- | | [/p](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/p/SKILL.md) | Push the current branch. Sets upstream when the branch has none. Refuses to force-push. | | [/m](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/m/SKILL.md) | Attempt to squash merge the current PR without waiting for CI. Required checks, reviews, and other repository protections still apply. Deletes the branch after merging. | | [/wm](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/wm/SKILL.md) | Wait for CI to pass, then squash merge. Stops and reports on failure; never merges past a red check. | ### CI | Command | What it does | | --- | --- | | [/ci](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/ci/SKILL.md) | Report CI status for the current branch or its PR. Pulls the failing job's log and gives you the smallest excerpt that shows the cause. Read-only. | | [/fci](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/fci/SKILL.md) | Diagnose the failing CI run, fix the root cause, push, and watch the rerun. Does not skip or loosen checks. Stops on external blockers or after one unsuccessful fix round. | ### Pull requests | Command | What it does | | --- | --- | | [/prd](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/prd/SKILL.md) | Rewrite the PR title and description from the full diff against the base branch. Useful when your commits evolved beyond the original description. The diff is the source of truth. | | [/cl](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/cl/SKILL.md) | Close issues resolved by the branch's PR. Checks completed checklist items, closes only fully resolved issues, and leaves incomplete issues open with a progress comment. | ### Code quality | Command | What it does | | --- | --- | | [/lint](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/lint/SKILL.md) | Run every linter, formatter, and typecheck the repository has. Fix to zero, pre-existing violations included. Won't touch lint configuration to make output clean. | | [/fa](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/fa/SKILL.md) | Address findings from the most recent review, audit, or check in this session. After /ci or a code review reports problems, /fa attempts each fix and reports anything skipped. Pass a range to narrow it down (e.g., /fa 2-4). | ### Rules and dependencies | Command | What it does | | --- | --- | | [/rule](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/rule/SKILL.md) | Create or update a project rule. | | [/deps](https://github.com/svyatov/agent-toolkit/blob/main/plugins/shortcuts/skills/deps/SKILL.md) | Detect package managers from manifests and lockfiles, update outdated dependencies, run the repository's checks, and commit without pushing. Requires a clean working tree. Respects version constraints and reports updates it cannot keep after verification. | ## How to install shortcuts Two commands: ```bash claude plugin marketplace add svyatov/agent-toolkit claude plugin install shortcuts@svyatov-agent-toolkit ``` For Codex, use these two commands: ```bash codex plugin marketplace add svyatov/agent-toolkit codex plugin add shortcuts@svyatov-agent-toolkit ``` That's it. The shortcuts show up as `/c`, `/cb`, `/cpr`, etc. in your agent's slash command list. ## What else is in agent-toolkit Shortcuts is one plugin in the toolkit, and yes, my most-used one, which is the whole point of naming it that. But there are others I reach for almost as often. `refactor` assesses code structure and makes justified changes while preserving behavior. `improve-architecture` works at a higher level: you point it at a broader slice of the codebase and it assesses module boundaries and coupling. Both can conclude that no changes are needed. Both see heavy use after long agentic sessions where the code works but the design has drifted. The most recent addition is `atomic-commits`, whose Claude Code hook nudges the agent when a diff grows too large. That's useful when a session has gone long and the agent keeps appending to the same branch instead of splitting work out. There's also `browser-bugs` (audits frontend code against a catalog of cross-browser problems), `prior-art` (searches arXiv for relevant work before you design a non-trivial technical mechanism), `contribute` (prepares an upstream issue or PR for a third-party dependency and asks before submitting it), `browser-qa`, `generate-dockerfile`, and `generate-favicon`. The full list is in the [repo](https://github.com/svyatov/agent-toolkit). ## The point You aliased your shell commands after the third time you typed the same thing. This is the same instinct. Your agent is just a slower terminal. My specific shortcuts reflect my specific workflows. Yours would probably look different. The repo is there if you want to clone it and gut the parts that don't fit — or just read through the skill files and write your own from scratch. The idea is the thing worth stealing, not the commands themselves. --- ## System 1 AI models: the idea that existed before Jev, and why you should use it anyway - URL: https://svyatov.com/blog/system-1-ai-models-the-idea-that-existed-before-jev/ - Date: 2026-09-21 - Tags: ai, classification, llm TypeSafe [announced Jev on September 15, 2026](https://typesafe.ai/blog/introducing-system-one-models-and-jev), presenting it as its first System One model: a model built to return structured decisions instead of generated text. It's a useful idea with a longer history than the branding suggests. Classification without text generation existed well before Jev. That does not mean Jev's architecture or training method is identical to earlier work. But if you're building anything that involves routing, classification, or structured decisions, the broader pattern deserves a look. --- ## What these models actually do A common way to use an LLM for classification is to ask a question, wait for generated tokens, then read the answer. Is this message spam? Which intent does this query match? Does this content violate a policy? The output can be a single label or structured JSON, but it still passes through text generation. The models discussed here score defined outcomes without generating a text answer token by token. Their implementations differ, so a shared interface does not establish a shared architecture. [Jev's API](https://docs.typesafe.ai/introduction), also available through [Cloudflare AI](https://developers.cloudflare.com/ai/models/typesafe/jev/) as `typesafe/jev`, evaluates typed questions against an input state: 1. [**Noul**](https://docs.typesafe.ai/primitives/noul) returns the probability that a statement is true, from 0 to 1. It has no separate confidence field. 2. [**Choice**](https://docs.typesafe.ai/primitives/choice) returns a selected option, probabilities over your options, and a confidence value. 3. [**Score**](https://docs.typesafe.ai/primitives/score) returns a probability-weighted score over ordered rubric levels, plus the distribution and confidence. TypeSafe reports end-to-end responses of 70 to 500 ms and speedups of 40 to 200 times in its comparisons. Its headline results, 193.6 times faster and 444.6 times cheaper, come from its own workflow evaluations. The company says those gains are likely at the high end of real-world results. Treat these as [vendor benchmark results](https://typesafe.ai/blog/introducing-system-one-models-and-jev), not a guarantee for your workload. A probability output is also not proof of calibration. Neural classifiers can be [overconfident](https://proceedings.mlr.press/v70/guo17a.html). TypeSafe's [confidence field](https://docs.typesafe.ai/confidence) summarizes the shape of the output distribution; it is not itself a measured probability that the selected answer is correct. Test accuracy and calibration on your own data before using thresholds to automate decisions. ## The idea before the branding There is clear prior work on choosing labels from natural-language descriptions. For example, [Yin, Hay, and Roth's 2019 paper](https://arxiv.org/abs/1909.00161) frames zero-shot text classification as textual entailment. That establishes a history for the broader pattern, without establishing that Jev uses the same mechanism. There is also a more recent connection. On March 30, 2025, Nandakishor Mukkunnoth published [SalesRLAgent](https://arxiv.org/abs/2503.23303), a reinforcement-learning approach to predicting conversion probability during sales conversations. In his [Laya write-up](https://laya.convaiinnovations.com/), he connects that research to his later general-purpose decision models. The earlier paper is about a sales-specific system; it does not establish that today's Laya was available in March 2025 or that it has Jev's exact architecture. Several public projects now offer related models or local inference tools: 1. [**Laya**](https://huggingface.co/convaiinnovations/laya) is an Apache-2.0 model family with English and multilingual checkpoints. Its model card reports 39.5 ms for the English checkpoint and 32.8 ms for the multilingual checkpoint on one question using a T4 GPU. The multilingual variant advertises support for more than 100 languages; that does not imply equal accuracy across them. 2. [**von-1.0**](https://huggingface.co/wfzyx/von-1.0) uses a ModernBERT-large encoder. Its card advertises sub-25 ms inference, but its benchmark table lists about 62 ms on MPS/GPU and 300 ms on CPU. Those figures need their workload and hardware context. 3. [**decider-2b**](https://huggingface.co/Mapika/decider-2b) builds on Qwen3.5-2B-Base and returns distributions over typed question options in one forward pass. Its card explicitly describes it as an open reproduction of Jev. 4. [**plek-1**](https://huggingface.co/Drenel/plek-1) describes itself as Jev-inspired and scores candidate choices using sequence log-likelihoods. It is a related implementation, not evidence that this particular model preceded Jev. 5. [**Foq**](https://github.com/yohanargentina-oss/Foq) is a local System 1 inference engine. It belongs in the tooling category, rather than being another interchangeable model checkpoint. Jev's typed API and Cloudflare availability make the pattern easy to explore. TypeSafe says the System One name draws on Daniel Kahneman's distinction between fast, intuitive thinking and slow, deliberate reasoning. I find that a useful framing for deciding when software needs a quick judgment. Good packaging and distribution are real contributions. They can make an established class of problems easier to solve. The architectural and performance claims still need to be judged model by model. ## The familiar use cases Intent detection, content moderation, support ticket triage, and agent routing are natural classification tasks. If your system currently uses a generative LLM for them, a decision model is a candidate to benchmark. Whether it helps depends on accuracy, latency, cost, and the cases that need more reasoning or context. But I find the applications beyond that list more interesting. ## Five applications to explore These are design ideas, not claims that the models above have been validated for each task. ### IoT and edge decision gates Your temperature sensor reads 47°C. A fixed safety threshold belongs in ordinary code. A decision model could help with a different part of the workflow: combining an alert with a technician's notes and maintenance history to route a service request using natural-language criteria. Keep the safety rule independent of the classifier. Measure latency and memory use on the target device. Laya's GPU timings do not establish sub-millisecond inference or suitability for a small sensor controller, and calling a cloud service from an edge function does not mean the model runs on the device. ### Adaptive UX branching Onboarding flows are full of decisions: does this user need the advanced tutorial or the beginner one? Should we show the integration setup screen or skip it? A decision model could classify a user's stated goal and suggest the next step, with a default path for uncertain results. This is most interesting when the input is free-form text. For an explicit account setting, a simple rule may be enough. Measure the added response time before putting a model call on every step, and let users correct the route. ### Contract pre-screening Contract clause classification has an established research basis: [CUAD](https://www.atticusprojectai.org/cuad/) contains 510 contracts annotated for 41 clause types. A decision model could help reviewers find relevant clauses and prioritize review against defined criteria. That needs testing on representative contracts, including clauses whose meaning depends on other sections. A missed clause can matter more than an extra flag. Classification can help organize review; it does not establish legal compliance or justify treating unflagged sections as safe. ### Game NPC decisions TypeSafe's launch post includes a Doom demonstration making roughly ten queries per second from structured game state. That suggests a possible role for these models in high-level decisions, such as interpreting a player's instruction or choosing an NPC's next goal. It does not establish frame-rate inference. A game running at 60 frames per second has about 16.7 ms for the entire frame. Run model decisions asynchronously or on selected events, and let normal game logic handle movement and immediate reactions. Checking whether health is below a known threshold still needs only a comparison. ### Targeted experiments A classifier could identify users whose stated goal makes them eligible for an experiment. For example, an onboarding experiment might apply only to users who want to import data. Define and freeze that eligibility rule using information available before treatment, then randomly assign eligible users to control or variant B. [Microsoft's experimentation guidance](https://www.microsoft.com/en-us/research/articles/patterns-of-trustworthy-experimentation-pre-experiment-stage/) explains why targeting must preserve comparable treatment and control groups. Sending high-confidence users to B and everyone else to control would introduce selection bias. A targeted experiment measures the effect within the eligible population, and a smaller sample does not guarantee faster statistical significance. A classifier's confidence also does not establish how much a user will benefit from treatment. --- ## The actual recommendation Test the pattern on a classification or routing task that currently goes through a generative LLM. Compare it with your current system and with a simple classifier or rule. Measure wrong decisions and missed cases as well as latency and cost. The linked model cards give you a starting point for local alternatives. Similar API shapes can reduce integration work, but context limits, language coverage, calibration, and deployment requirements still differ. Open weights also leave you with hosting costs. The useful question is simple: does this part of the system need generated text, or does it need a decision over known outcomes? Answer that first, then choose the model. --- ## Five ways to build a save panel, three of them correct - URL: https://svyatov.com/blog/five-ways-to-build-a-save-panel-three-of-them-correct/ - Date: 2026-08-07 - Tags: typescript, javascript, webdev, programming Here is a save panel: a spinner, an error banner, a dirty marker, a confirm dialog, and a closed flag. Five booleans, so thirty-two combinations. Have you ever written down all thirty-two? I built it five times to find out what a statechart is actually worth. The first version breaks on the very first event I throw at it. The last version is the longest file of the five. Every number I measured comes out of a script, and the command that printed it sits right above the output. The numbers I did not measure are linked instead. Versions: `xstate@5.32.5`, bun 1.3.14, TypeScript 7.0.2 and 5.9.3, 2026-08-06. One scope note, because it cuts against the tool I am measuring. All five versions are pure functions from a state and an event to a new state: no view layer, no network, no request that actually goes anywhere. So XState's `invoke` never appears here, and neither does the cancellation that comes with it (which is a real part of what the library is for, and would have made one of the bugs below its problem rather than mine). I measure the shape of the state, and only that. ## The spec, as eight rules If the rules live in prose, every later claim is an opinion. So they live in code, once, and every implementation gets checked against the same eight. Each rule looks at one transition: the screen before, the screen after, the event, and whether the event was a reply to a save that is no longer running. ```ts // R3: a reply from a save that is no longer in flight changes nothing. R3_stale_reply_ignored: ({ stale, before, after, beforeInflight, afterInflight }) => stale && (!sameView(before, after) || beforeInflight !== afterInflight) ? "a stale reply changed the screen" : null, // R7: once closed, nothing changes. R7_closed_is_terminal: ({ before, after }) => before.closed && !sameView(before, after) ? "the screen changed after closing" : null, // R8: a closed panel is not still saving, erroring, or asking. R8_closing_stops_everything: ({ after }) => after.closed && (after.spinner || after.errorBanner || after.confirmDialog) ? "the panel closed while still saving, showing an error, or asking" : null, ``` A rule returns a complaint or `null`, and `sameView` just compares the five on-screen signals. The other five rules cover the ordinary things: no spinner and error banner at once, a new save clears the old error, no second save while one is in flight, a successful save leaves the draft clean, and closing with unsaved edits asks first. A walker drives all five versions. It starts at the initial state, fires every event, and repeats from everything new it finds. It also invents two kinds of server reply: one for the save the user is watching, and one for a save nobody is watching any more. That second one matters more than it sounds. ## One: five booleans This is the shape a panel starts as, and I wrote it as well as I could rather than as badly as I could. It already refuses a second save. It already clears the error banner when a new save starts. ```ts function next(s: S, e: Ev): S { if (s.isClosed) return s; switch (e.type) { case "EDIT": return { ...s, isDirty: true }; case "SAVE": if (s.isSaving) return s; return { ...s, isSaving: true, hasError: false }; case "CANCEL": return { ...s, isSaving: false }; case "SAVE_OK": return { ...s, isSaving: false, hasError: false, isDirty: false }; case "SAVE_ERR": return { ...s, isSaving: false, hasError: true }; case "CLOSE": if (s.isDirty) return { ...s, isConfirming: true }; return { ...s, isClosed: true }; case "CONFIRM_DISCARD": return { ...s, isConfirming: false, isClosed: true }; case "KEEP_EDITING": return { ...s, isConfirming: false }; } } ``` It breaks R3 on the first event the walker tries. A `SAVE_ERR` arrives belonging to a save that is not running (the user cancelled, say, and the request landed anyway). The panel shows an error for something nobody is waiting on. Look at the code and you cannot fix it. `case "SAVE_ERR"` has nothing to compare against. Five booleans can say *a save is happening*. They cannot say *which one*. That is the point where flags start disagreeing with each other, and it is not the tired `isLoading && isError` complaint. The mainstream answer to that one has been an enum since 2020, when Kent C. Dodds wrote [Stop using isLoading booleans](https://kentcdodds.com/blog/stop-using-isloading-booleans). Your reader already agrees. This is a different failure: the flags are individually correct and collectively meaningless. ## Two: name the request So a reviewer says: give the request a number. Fine. ```ts case "SAVE": if (s.isSaving) return s; return { ...s, isSaving: true, hasError: false, saveToken: s.nextToken, nextToken: s.nextToken + 1 }; case "SAVE_ERR": if (e.token !== s.saveToken) return s; return { ...s, isSaving: false, hasError: true, saveToken: null }; ``` R3 is fixed. R8 still breaks. `SAVE`, then `CLOSE` on a clean draft. The panel closes with `saveToken` still set and `isSaving` still true. The screen is gone, and the model thinks a save is in flight behind it. The moment you add a token you have stopped using flags and started storing state. The last three versions are all arguments about *what shape* that state should take. ## Three: a union for the save Here is the version the skeptic asks for, and the skeptic is not a strawman. Here is one, [in 2023](https://news.ycombinator.com/item?id=35330873): *"I think this is solved more generally with a discriminated union in typescript. A state machine is the wrong solution unless you also need to restrict transitions themselves."* ```ts type Save = { tag: "idle" } | { tag: "saving"; token: number } | { tag: "error" }; type S = { save: Save; dirty: boolean; confirming: boolean; closed: boolean; nextToken: number; }; ``` The token now lives inside `saving` and nowhere else. You cannot read a token off an idle save, because there is nothing to read. It passes all eight rules. That is worth sitting with, because it is the honest answer to the question everyone asks first. A tagged union and a `switch` solve this feature. No library, twenty-four lines of transition logic, done. It also answers a question I found asked in April 2026 in an eighty-six comment thread, [with no reply](https://news.ycombinator.com/item?id=47908833): *since the state chart itself doesn't contain any data, where does the data live, and how do you handle data that's only valid in certain states?* The union's answer is the good one. Data hangs off the state that owns it, so the compiler stops you reading it anywhere else: ```ts type State = | { tag: "guest" } | { tag: "member"; user: string }; export function greet(s: State): string { // `user` exists on exactly one member of the union, and this reads it from the whole union. return s.user; } ``` ```plaintext error TS2339: Property 'user' does not exist on type 'State'. Property 'user' does not exist on type '{ tag: "guest"; }'. ``` XState has no equivalent. Its `context` is one object typed once for the whole machine, so a field that only makes sense in one state is typed as present in all of them: ```plaintext PASS context.user is reachable, and null, while the machine is in `guest` guest context.user = null (the type says string | null in EVERY state) ``` The union asks the compiler a question the machine cannot be asked. That is a real thing it wins, and none of the articles I read concede it. So why keep going? Because the union's clean sheet is held up by two lines somebody has to remember to write: ```ts const close = (s: S): S => ({ ...s, closed: true, confirming: false, ...(opts.closeResetsSave ? { save: { tag: "idle" as const } } : null), // line one }); function next(s: S, e: Ev): S { if (opts.closedGuard && s.closed) return s; // line two ``` I made both switchable so the run can price them: ```bash bun run src/verify-three-ways.ts ``` ```plaintext variant rules broken which union reducer closedGuard=true closeResetsSave=true 0 none union reducer closedGuard=true closeResetsSave=false 1 R8 union reducer closedGuard=false closeResetsSave=true 2 R7,R8 union reducer closedGuard=false closeResetsSave=false 2 R8,R7 ``` One line says *once closed, ignore everything*. The other says *closing also stops the save*. Neither is enforced by the shape. They are vigilance, written down. And the shape allows twenty-four of the thirty-two screens while the code only ever reaches fourteen. Ten configurations exist that nothing produces and nothing checks. `closed: true` next to `save: { tag: "saving" }` is one of them. ## Four: a state machine, by hand A state machine is three things: a set of states, a set of events, and a table saying which event moves you from where to where. That is the whole idea. It predates all of this and needs no library. Written out, the states cover every combination of what the save is doing and whether the dialog is up. Here is one row of that table, for the state where a save is running and the dialog is down: ```ts savingHidden: { EDIT: { to: "savingHidden", then: dirty }, CANCEL: { to: "idleHidden", then: clear }, SAVE_OK: { to: "idleHidden", when: isFresh, then: saved }, SAVE_ERR: { to: "errorHidden", when: isFresh, then: clear }, CLOSE: [{ to: "savingConfirming", when: isDirty }, { to: "closed", when: notDirty, then: clear }], }, ``` Three keys, and I picked the names: `to` is the next state, `when` is a guard that has to hold, and `then` updates the data alongside the state. A list is tried in order, so `CLOSE` asks the dialog first and closes only if the draft is clean. The helper named `clear` is the one worth reading twice: it does not clear the error, it forgets the token of the save in flight. Seven states, twenty-eight arrows, no dependency. It breaks nothing, and it reaches exactly the same fourteen screens as everything that follows. Note what fixed R8 here, because it is easy to credit the wrong thing. `closed` became a *state* instead of a field sitting beside the save. A state cannot be occupied at the same time as `savingHidden`, so "closed while saving" stopped being expressible. That is states beating flags. It has nothing to do with statecharts yet. So, do you need the library? At this size: no. GitLab reached the same conclusion and wrote [about a hundred lines](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/lib/utils/finite_state_machine.js) of finite state machine into their own utils folder in 2021, where it still sits with no hierarchy and no regions. Expo went further: they keep an XState model of their update logic in TypeScript [as a reference document](https://xstate-in-the-wild.transistor.fm/episodes/xstate-at-expo-with-doug-lowder/transcript) and ship the real thing hand-written in Kotlin and Swift. Look again at that table, though. `EDIT` appears in every single row. `savingConfirming` exists only because saving and confirming can happen together. Both of those are the smell. ## The two ideas David Harel worked the two ideas out over 1982 and 1983, and he says what they are in one sentence: > Besides a host of other constructs, the two main ideas in statecharts are hierarchy and orthogonality, and these can be intermixed on all levels. Think about the light switches in a house. **Hierarchy** is the breaker. The kitchen has its own switch, and so does the porch, but there is one breaker upstream of both, and throwing it turns off every room at once. Nobody wires "and also go dark when the breaker trips" into each individual lamp. That is a state containing states: being in `open` means being in exactly one of its children, and anything true of `open` is true of all of them. It is XOR, and it is why `EDIT` is written once on the parent instead of six times on the leaves. **Orthogonality** is the two switches. The kitchen light does not know or care whether the porch light is on. You could label all four combinations on a single dial (kitchen-on-porch-off, kitchen-off-porch-on, and so on) and it would work, and you would relabel the whole dial the day somebody adds a hallway. Or you keep two switches. That is what the panel's save and its dialog are: one list of seven names becomes two lists of three and two. It is AND, and it is why `savingConfirming` stops needing a name. The four combinations still exist in the house. You just stopped writing them down. Harel is careful about what orthogonality is not, and every tutorial I read got this wrong: > Orthogonal state-components in statecharts are not the same as concurrent or parallel components of the system being specified ... but simply to help structure its state space. So: not threads, and nothing runs at the same time. Two switches on one wall. Here is the panel with both ideas applied: ```plaintext draft │ ├── open two regions, both live at once │ │ on EDIT: mark dirty <- written once, works from every leaf below │ │ │ ├── save ├── dialog │ │ idle │ hidden │ │ SAVE -> saving │ CLOSE [dirty] -> confirming │ │ saving │ CLOSE [clean] -> closed │ │ SAVE_OK [fresh] -> idle │ confirming │ │ SAVE_ERR [fresh] -> error │ KEEP_EDITING -> hidden │ │ CANCEL -> idle │ CONFIRM_DISCARD -> closed │ │ error │ │ │ SAVE -> saving │ │ └── closed (final) leaving `open` exits BOTH regions ``` ## Five: the statechart Same spec, same eight rules. The guards and actions get declared first, then the shape. ```ts export const machine = setup({ types: {} as { context: Ctx; events: Ev }, guards: { isDirty: ({ context }) => context.dirty, isFresh: ({ context, event }) => (event.type === "SAVE_OK" || event.type === "SAVE_ERR") && event.token === context.token, }, actions: { startSave: assign({ token: ({ context }) => context.nextToken, nextToken: ({ context }) => context.nextToken + 1, }), forgetSave: assign({ token: null }), markSaved: assign({ dirty: false, token: null }), markDirty: assign({ dirty: true }), }, ``` `isFresh` is the same token check from version two, named once and reused by both replies. Then the shape. `open` is the parent, `type: "parallel"` makes its children regions rather than alternatives, and `EDIT` sits on the parent: ```ts }).createMachine({ id: "draft", context: { dirty: false, token: null, nextToken: 0 }, initial: "open", states: { open: { type: "parallel", // Hierarchy: EDIT is written once here and covers every leaf below it. on: { EDIT: { actions: "markDirty" } }, states: { // Orthogonality: these two regions are both live and neither knows about the other. save: { initial: "idle", states: { idle: { on: { SAVE: { target: "saving", actions: "startSave" } } }, saving: { on: { SAVE_OK: { guard: "isFresh", target: "idle", actions: "markSaved" }, SAVE_ERR: { guard: "isFresh", target: "error", actions: "forgetSave" }, CANCEL: { target: "idle", actions: "forgetSave" }, // No handler for SAVE: a second save cannot start while one is in flight. }, }, error: { on: { SAVE: { target: "saving", actions: "startSave" } } }, }, }, ``` Read the `saving` block again. The rule against a second save while one is in flight is expressed by leaving something out. The dialog region never mentions the save. Two things in it need a word. `#draft.closed` is an absolute target: the `#` means "start from the machine's id", which you need here because `closed` is not a sibling of `hidden`. And a list of transitions is tried in order, so the guarded entry gets first refusal and the unguarded one is the fallback: ```ts dialog: { initial: "hidden", states: { hidden: { on: { CLOSE: [{ guard: "isDirty", target: "confirming" }, { target: "#draft.closed" }] }, }, confirming: { on: { KEEP_EDITING: { target: "hidden" }, CONFIRM_DISCARD: { target: "#draft.closed" } }, }, }, }, }, }, // Leaving `open` exits both regions. Nothing has to remember to stop the save. closed: { type: "final" }, }, }); ``` `closed` is a sibling of `open`, one level up. The save region is never asked to stop. It stops because it no longer exists. (That is the breaker again: nothing tells the kitchen light to go off.) That is the union reducer's `closeResetsSave` line, deleted and replaced by a shape. Now run all five: ```bash bun run src/verify-three-ways.ts ``` ```plaintext SPEC: a draft editor's save panel. 8 rules, 8 events, 5 on-screen signals (2^5 = 32 screens). implementation screens allowed screens reached never checked rules broken booleans 32 of 32 21 11 R3,R8 booleans + request token 32 of 32 21 11 R8 union reducer 24 of 32 14 10 none flat machine, no library 14 of 32 14 0 none statechart (XState v5) 14 of 32 14 0 none ``` **On this spec the statechart wins nothing on correctness.** The union reducer catches every rule it catches, and so does a flat machine with no dependency at all. All three reach an identical set of fourteen screens, and the run fails on purpose if they ever diverge. Do not read too much into the "screens allowed" column, though. It flatters machines by construction (a machine's set of possible states *is* its list of declared states, so its slack is structurally zero), which means it separates machines from flags and tells you nothing about statecharts against flat machines. And the walker is a search, not a proof: it treats two internal states that look identical on screen as one node. So a second check expands every path to a fixed depth, with no de-duplication at all: ```bash bun run src/probe-exhaustive.ts ``` ```plaintext The shipped walker de-dups by (screen, save in flight?). This one does not de-dup at all: every event path to depth 6, on all three implementations that broke no rule. union reducer paths= 352971 violations=none flat machine, no library paths= 374841 violations=none statechart (XState v5) paths= 374841 violations=none PASS: the de-duplicating walker hid nothing. Same verdict under the exhaustive one. ``` Six events deep is a bound, not a proof. It is a much wider net than the first walk, and it is still a net. ## So what did that buy? Arrows. ```bash bun run src/verify-explosion.ts ``` ```plaintext Same spec, same behaviour, two shapes: flat machine 7 states, 28 arrows written by hand statechart 6 leaf states (10 nodes with parents), 10 arrows written ratio 2.8x fewer arrows in the statechart ``` I do not want you to take that on faith, and I did not either. The script flattens the statechart mechanically: cross-product the two regions, copy each leaf's arrows into every combination it appears in, add the parent's arrows once per combination. It gets seven states and twenty-eight arrows. That is the hand-written flat machine, exactly, and the script exits non-zero if it ever stops matching. Which means I can add concerns and let it do the arithmetic. Each new concern below is a two-state toggle with one arrow per state. An "offline / online" indicator. A "compact / expanded" view. ```plaintext extra flat states flat arrows chart leaves chart arrows union: allowed / unchecked 0 7 28 6 10 24 / 10 1 13 68 8 12 48 / 20 2 25 160 10 14 96 / 40 3 49 368 12 16 192 / 80 4 97 832 14 18 384 / 160 ``` Four independent toggles is not an exotic feature (a save panel that also knows about the network, the layout, whether the document is shared, and whether you are on a phone). Ninety-seven states and eight hundred arrows, or fourteen states and eighteen arrows. But read the last column before you conclude anything, because **the union reducer is not on the exploding side of this table.** A toggle costs it one more boolean field, not a cross product of names. What grows for the union is the space nothing checks: at four toggles its shape admits 384 configurations, 160 of which nothing reaches and no rule inspects. The statechart's figure there is zero at every row, because a machine's shape is its list of states. So the choice the table actually offers is not statechart or explosion. It is: write the cross product out by hand, or keep a boolean field per concern and accept that most of what your type allows is never looked at. And here is the caveat that keeps the rest of it honest: **both machine columns describe the same program.** The configuration space did not shrink. Three regions of two states each is eight configurations either way: ```bash bun run src/verify-orthogonality.ts ``` ```json Three orthogonal regions, two states each: written down 6 leaf states, 6 arrows reachable 8 configurations the formalism 2^3 = 8 initial value {"a":"a1","b":"b1","c":"c1"} ``` Orthogonality does not make your program simpler. It makes the description shorter, and the description is the thing a person has to hold in their head. One more thing before I let the statechart off. Back in section three I knocked out the reducer's two hand-written lines to show they were vigilance rather than structure. It would be unfair to stop there, so I ran the same sweep on the statechart: ```plaintext statechart isFresh=true 0 none statechart isFresh=false 1 R3 ``` Turn off the token guard and the statechart breaks R3, exactly the way the flags version did on the very first event. Neither the hierarchy nor the two regions produce that guard. It is a line I wrote by hand, same as the reducer's two, and nothing complains when it goes missing. So the score is honest: the shape bought R7 and R8, in every version that made `closed` a state. It did not buy R3, in any version. Somebody has to write that one down. That is the whole trade. A statechart is a notation. ## Harel ranked state explosion second Which is exactly what it was built to be, and the story is not the one usually told. In December 1982 Harel took a consulting job: one day a week, Thursdays, at Israel Aircraft Industries, on the avionics team of the Lavi fighter. He describes it himself in a [2007 account](https://www.weizmann.ac.il/math/harel/sites/math.harel/files/users/user50/Statecharts.History.pdf) that he labels highly personal and subjective, so read it as testimony rather than measurement. The specification was two volumes of structured English, around a thousand pages each. He asked what he thought was a simple question: what happens when you press this button on the stick? They answered it. They opened volume B, found the clause, and read it to him. So he added a condition, and they found a different clause in the other volume. ```text Q1 what happens when you press this button? volume B, clause 19.11.6.10 Q2 ... even with an infra-red missile locked on a ground target? volume A, clause 6.12.3.7 Q5 ... the engineers phone the customer Q8 ... "even those people often did not have an answer" ``` "Those people" is the Air Force team that owned the requirements. The team knew exactly what algorithm the radar used to measure distance to a target, and could not say what happens when you press this button under all possible circumstances. Now the part everyone gets backwards. Ask why statecharts exist and you will be told: state explosion. Harel puts that second. > not only because of the number of states ... even more important seemed to be the pragmatic point of view The more important half, in his words, is that a flat list of states "has no means for modularity, hiding of information, clustering, and separation of concerns". He was complaining that you could not organize the states, not that there were too many of them. That is a notation problem described in the vocabulary of software design, and it is why the growth table above is the *second* reason to care rather than the first. The diagrams came last, and by accident. Harel first wrote a textual language, hierarchical "statocols" (structured state protocols, and the name did not survive either), and doodled pictures beside it to explain it. The engineers understood the doodles better than the language. Within weeks he was asking whether the pictures could replace the text rather than illustrate it. The paper was rejected for about two and a half years. One referee wrote that "the topic is good only for a very narrow audience". [Crossref](https://api.crossref.org/works/10.1016/0167-6423%2887%2990035-9) counted 4,392 citations of it on the day I looked. And the idea travelled a long way past the fighter jet. [SCXML](https://www.w3.org/TR/scxml/) became a W3C Recommendation in September 2015, with a normative interpretation algorithm and a conformance section, explicitly "based on CCXML and Harel State Tables". [Qt ships an engine for it](https://doc.qt.io/qt-6/qtscxml-index.html) that generates C++. Do not read that as portability for the code in this post, though: XState says it is "inspired by" SCXML and claims no conformance, so a machine written here does not move to another engine. UML state machines are, in the OMG's lineage, an object-based variant of Harel's statechart. NASA JPL [generated flight code from them](https://www.state-machine.com/doc/Benowitz2006.pdf) for the Space Interferometer Mission, and Deep Space 1 was their first mission to do it, though the public JPL autocoder repository is a ground tool whose header reads "(NO FLIGHT CODE ALLOWED)". One tool that sells the notation, meanwhile, refuses the word. [MathWorks Stateflow](https://www.mathworks.com/products/stateflow.html) generates C, C++, VHDL and Verilog, and its customer stories name surgical device control and antenna stabilization. Its product page never once says "Harel" or "statechart". It says state transition diagrams and truth tables. ## Splitting a machine, and the types Everything above is one small machine. The complaint I kept running into starts with the second one: people try to split a definition into reusable pieces and the types fight back. That complaint dates from XState v4, so I re-ran it against what ships today, on both current TypeScript majors: ```bash bun run src/verify-ts-splitting.ts ``` ```plaintext xstate 5.32.5, tsc --strict, TypeScript 7.0.2 and 5.9.3 7.0.2 5.9.3 A shared sub-state object, spread into two machines FAILS TS2345 FAILS TS2345 A2 the same chunk, with `as const` FAILS TS2345 FAILS TS2345 A3 the same chunk, typed from the builder's config type compiles compiles B split into a child machine and invoked compiles compiles C persist a snapshot and restore it, no `any` compiles compiles D config chunk in another module, guard named in setup() FAILS TS2345 FAILS TS2345 D2 the same chunk, with `as const` compiles compiles D3 the same chunk, typed from the builder's config type compiles compiles E the documented way: setup(...).createStateConfig(...) compiles compiles Both compilers agree on every case. ``` The naive split does still fail. Plain TypeScript causes it, though, not statecharts: pull a chunk into a bare object literal and `"isHigh"` widens from a literal to `string`, and the config type wanted the literal. The fix is documented and I had missed it. `setup(...).createStateConfig(...)` has shipped since 5.21.0 and it compiles clean with the guard still named as a string, no cast: ```ts const builder = setup({ types: {} as { context: Ctx; events: Ev }, guards: { isHigh: ({ context }) => context.count > 3 }, }); export const states = builder.createStateConfig({ initial: "low", states: { low: { on: { BUMP: [{ guard: "isHigh", target: "high" }, { target: "low" }] } }, high: {}, }, }); ``` Do not reach for `as const` instead. It rescues case D2 and stops working the moment the chunk contains an inline `assign(...)`, which is case A2, still failing above. Harel, incidentally, would not have started here at all. "No one is encouraged to specify a single statechart for an entire system," he writes, footnoting that his own famous digital-watch example did exactly that for presentation reasons. ## The bill The statechart is the longest of the five files: ```bash bun run src/verify-cost.ts ``` ```plaintext lines of code, blank and comment lines dropped: whole file transition logic only booleans 62 23 booleans + token 68 25 union reducer 70 24 flat machine 94 40 statechart 116 57 (whole-file counts include the adapter each version needs to join the test harness) ``` Read the right column (the left one counts each version's glue into my test harness, which is my problem and not yours). Fifty-seven lines of transition logic against the union reducer's twenty-four, for identical behaviour. That gap is real, and I did not measure where or whether it closes, so I will not tell you that it does. Then the bytes. And here I got a surprise, because I assumed the weight was the runtime: ```bash bun run src/verify-cost.ts # same script, second half of its output ``` ```plaintext nothing (baseline) min 24 B gzip 44 B (esbuild 44 B) xstate min 42362 B gzip 13965 B (esbuild 12697 B) the builder only min 42333 B gzip 13947 B (esbuild 12688 B) the runtime only min 9937 B gzip 3452 B (esbuild 3088 B) pure transitions min 10379 B gzip 3586 B (esbuild 3225 B) @xstate/store min 7330 B gzip 2854 B (esbuild 2789 B) the two bundlers differ by at most 11% on any real row. ``` The thing that drives a machine is three and a half kilobytes. The thing that *defines* one is fourteen. Of the 13,965 bytes you actually ship, the runtime is 3,452, so three quarters of it is the notation. (Do not add the builder and the runtime together: they overlap heavily, so the two numbers are not a split of the total. And never quote a kilobyte figure without saying which bundler produced it, which is what that eleven percent is doing there.) While measuring that, I noticed `@xstate/store` advertises itself as "**Extremely small**: less than 1kb minified/gzipped". Today it measures 2,854 bytes gzipped. I installed version 1.0.0 to check, and there the claim was true: 533 bytes. The package grew and the line did not. More costs, none of which the field prices: **What you learn expires.** XState has shipped three incompatible ways to write a machine in three majors. ```text 2018-10-29 v4 Machine(...) cond: interpret(...) 2023-12-01 v5 createMachine(...) guard: createActor(...) setup({ types }) 2026-06-20 v6 alpha the v5 action and guard creators removed; schemas replace types ``` The v4-to-v5 [migration guide](https://stately.ai/docs/migration) runs 2,237 lines with 47 breaking changes, and some change meaning rather than spelling: transitions became internal by default, and child state nodes are always re-entered. A chart drawn against v4 behaves differently under v5. Then [v6 alpha](https://github.com/statelyai/xstate/releases/tag/xstate%406.0.0-alpha.1) arrived in June 2026 and deleted the vocabulary I used above: `assign`, `raise`, `sendTo`, `enqueueActions`, and the `and`, `or` and `not` guards. That is why every snippet here is stamped 5.32.5, and why you should check the date on any XState article before you copy from it, this one included. **Learning it is the cost everyone names first.** I cannot measure this and neither can anyone else, so here it is as testimony: one practitioner puts the curve "more similar to rx-js or fp-ts than a state manager", another says "building state machines is an art in and of itself and I had to throw away my first implementation". Take those as reports rather than as a number, but notice that three of the four introductions I read name the learning curve as the top cost and then move on. **The diagram costs money, or is abandoned.** The payoff people rate highest is showing the chart to someone who does not read code. The old visualizer repository is [archived](https://github.com/statelyai/xstate-viz) and its README now reads "XState (Legacy) Visualizer". The VS Code extension was last updated in January 2024 and the docs still say it is not compatible with v5, which shipped in December 2023. The current editor is a product: free if your projects are public, [$33 a month](https://stately.ai/pricing) billed annually or $39 monthly if they are not. **The other advertised payoff is also between homes.** Generating test paths from the machine is one of the benefits the introductions I read put near the top. I hand-rolled the exhaustive walker above; XState ships that idea too, and its documentation page currently says the utilities have moved into `@xstate/graph` and that the docs for them are "coming soon", while what is written is for a beta of the package they replaced. **That payoff is also contested.** A former gadget.dev engineer, in the same 2026 thread, reports the opposite result: "we started with hierarchical statecharts as a way for users to specify their behaviour ... No matter what we did, users just found it incredibly confusing." He also reduced "1000+ lines of very hard to read and extend statechart code to a few hundred lines of imperative code" and found that easier than fixing the bugs hiding in it. He is not an opponent ("I love the idea of statecharts, I just have scars from dealing with them"). One person's experience, self-reported, and worth more than a benefits page. **Some things it will not catch.** Send an event the current state does not handle and XState swallows it: the actor stays where it was, says nothing, and carries on. A typo in a target *does* throw, early, at `createMachine` time before any actor exists, which beats a hand-rolled switch where a mistyped string waits until runtime. But TypeScript will not catch that typo. And this machine constructs without complaint and then never finishes starting: ```ts createMachine({ initial: "a", states: { a: { always: "b" }, b: { always: "a" } } }); ``` The docs say XState "will help guard against most infinite loop scenarios" and give a rule: if a target is declared, it should differ from the current state node. Both of those targets do differ. It hangs anyway. ```bash bun run src/verify-behaviour.ts ``` ```json PASS a typo'd target throws at createMachine(), before any actor exists Invalid transition definition for state node '(machine).a': Child state 'typoState' does not exist on '(machine)' PASS an unhandled event changes nothing and warns nothing value a -> a, can() false, warnings 0 PASS manipulation check: the same actor DOES move on an event it handles a -> b PASS a targetless self-transition preserves the active child {"process":"step3"} PASS a self-transition with an explicit target resets it to the initial child {"process":"step1"} PASS an always/always cycle constructs fine and then never finishes starting printed: "constructed"; killed after 5s ``` The third line is there because the second is a claim about an absence, and an absence proves nothing unless you show the thing was listening. Lines four and five are one character apart: an explicit target re-enters the state even when it is the state you are already in. A hand-written transition table does catch the bogus target that XState's types miss, but only if you tie its targets to the state union: ```ts type Table = { [S in State["tag"]]?: { [E in Event["type"]]?: State["tag"] } }; ``` Write the typo into a free-standing literal type instead, with no tie back to `State`, and it compiles clean. The check comes from that line, not from having used a union. ## When not to reach for one The test is mechanical, and you can run it on your own code in about a minute: **count your nested states and your parallel regions. If both are zero, you have written a state machine and paid for a statechart.** ```plaintext nested states? no ─┐ parallel regions? no ├─▶ you have a state machine. Write the switch. `after` timers? no │ history states? no ─┘ any of them yes ─────▶ you are using the notation. Keep it. ``` Timers and history states are on that list because XState hands you both as primitives, `after` being the one-line version of a delayed transition. You can write either by hand, so this is a question of what you are getting for the dependency rather than of what is possible. And it tests the library, not the idea: a flat machine is a fine thing to have, it just does not need fourteen kilobytes to be one. In October 2025 the mapping library lonboard opened an [issue](https://github.com/developmentseed/lonboard/issues/916) saying "The current XState implementation is overkill for our simple UI interactions". The [migration to Zustand](https://github.com/developmentseed/lonboard/pull/1042) merged that December. The machine they deleted, [pinned at the commit before the merge](https://raw.githubusercontent.com/developmentseed/lonboard/0577b0722ccbcffda86f1a4ff4aedd01394e258c/src/xstate/machine.ts), was 180 lines, three top-level states, six event types, and zero nested-states blocks. Flat. It was a state machine the whole time. The honest code delta is small: 375 lines of application source removed, 283 added, so about ninety lines net. The pull request header says +1425/-488, but roughly eleven hundred of that is new Playwright tests, and quoting it as a code-size result would be dishonest. Their own stated goal was not fewer lines. It was to "Lower barrier to entry for JS developers". The vendor says something close to the same thing, which is stronger evidence than a skeptic saying it, because the vendor has every reason not to. The XState README tells you to start with `@xstate/store` "if you just need a store" and graduate later. When they announced that store in 2024 they wrote that teams were using XState "for simple data updates, where using full state machines may be overkill". The author's own rule, from an April 2026 thread: statecharts "are most useful when you have behavior where the answer to 'what happens next?' depends on both the current state & the event". Leaving is not free, either. In a 2024 [discussion](https://github.com/statelyai/xstate/discussions/4708) titled "Need suggestions on migrating away from XState", the poster opened with "XState is just way too sophisticated for our needs" and, ten months later, wrote: "We haven't done the migration because this is a big undertaking and we don't have the resources for it at the moment." And one widely shipped engine threw one of the two ideas away on purpose. [Zag.js](https://github.com/chakra-ui/zag), which drives the components in Chakra UI and Ark UI, says "We don't follow the SCXML specifications" and instructs its own contributors to "Avoid using complex machine concepts like spawn, nested states, etc." Finite states, yes. Hierarchy, no. ## What else is there **A tagged union and a `switch`.** Already shown. For a flat model it is the right answer, it is shorter, and it types per-state data better. **Zustand, Redux, `@xstate/store`.** All stores. Worth knowing that `@xstate/store` is not a small statechart: the words `states`, `initial`, `parallel`, `guard`, `entry`, `exit` and `history` appear nowhere in its type surface. It is context and events. And `@xstate/fsm`, the small official state machine, is deprecated, so the ladder now goes from nothing to a store with no states to the full fourteen kilobytes, with nothing in between. **Behavior trees.** The competitor that won an entire industry. Similar to hierarchical state machines, except the building block is a *task* rather than a state, which turns out to suit game AI better. Halo, BioShock, Spore; Unity and Unreal both support them. **TLA+ and friends.** A different altitude: you model the algorithm and check the model, rather than running it. The AWS team's [report](https://lamport.azurewebsites.net/tla/formal-methods-amazon.pdf) also states the ceiling that applies to everything in this post, statecharts included: "TLA+ cannot verify code, only algorithms. Code can have bugs that the spec does not have." **Durable workflow engines.** AWS [Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html) calls its workflows state machines outright, and it does the thing a statechart in a browser tab cannot: a run stays alive for up to a year, and you are billed per transition. XState hands you a JSON snapshot and restores from it, which is not the same promise, because you own the storage and the uptime. One piece of prior art deserves naming, because the shape of this post is not new. In July 2020 Matt Pocock built [a modal three ways](https://dev.to/mattpocockuk/usestate-vs-usereducer-vs-xstate-part-1-modals-569e), counted the refactors each version needed under a changed requirement, and got 4, 4 and 2. Two things about it. The new requirement was a timed transition, which is the one case XState answers with a one-line primitive, so the setup favours the tool. And the promised part two never came. What I did not find anywhere is a discriminated union of *states* entered as a real contender, or anybody reporting a count instead of a verdict. --- So: count your nested states. Count your regions. If you have neither, write the switch, and know that you are in good company. If you have both, and you are writing `savingConfirming` by hand, you already have a statechart. You are just spelling it out one combination at a time. --- ## Your agent writes Python. The Ruby rule cuts that by a third. - URL: https://svyatov.com/blog/your-agent-writes-python-the-ruby-rule-cuts-that-by-a-third/ - Date: 2026-08-06 - Tags: ruby, ai, python, productivity Lucian Ghinda [published a post](https://allaboutcoding.ghinda.com/write-agent-scripts-in-ruby/) arguing you should tell your coding agent to write its throwaway scripts in Ruby. Here is the block he tells you to paste into your agent's instruction file, in full: ```markdown ## Scripts Write throwaway and utility scripts (data munging, one-off migrations, file renames, glue code) in Ruby, even in projects written in another language. If it needs a pipe, a loop, a conditional, or more than one line, it is a script: write it in Ruby, not Python, Node, or bash. Single self-contained commands (`grep`, `git status`) are fine as-is. Use only the Ruby standard library. If a gem would clearly save significant effort, stop and ask before using it. Put temporary scripts in a scratch or temp directory, not the repo root, and delete them when done unless asked to keep them. ``` I pasted it into my global `CLAUDE.md` the same evening. His argument is about review: he reads Ruby daily, so when the agent writes Ruby he stays a reviewer instead of nodding at a diff. He gives three reasons and not one of them is cost. So I went looking for the number he left out. "Does the rule save tokens" only means something against what the agent writes otherwise, so the first thing I had to do was take the block back out of my global config. An agent that already carries the rule cannot tell you what it would do without it. ## Measuring an agent without your config in the room Every arm below runs through `claude --safe-mode` on Claude Opus 5, which loads no `CLAUDE.md`, no skills, no plugins and no hooks. Two arms deliberately skip that flag, and I name them where they appear: they are the ones that measure what my own setup does to the result. It is worth knowing that my global config alone still carries a line telling the agent to write the minimum code that does the job, and another preferring bun over node. Four tasks, one for each kind of script the rule names: munge a log, rename a key across a tree of config files, renumber a pile of screenshots, turn one CSV into another. I took them from his list rather than inventing my own, so I could not quietly pick ground that suits Ruby. Three things about the setup are worth knowing before any number lands. All three are choices I made, and all three are arguable: - No arm pastes the rule itself. Each names a language and the standard-library constraint directly, which is what the rule produces rather than its own text. - The bash arm may not use `jq`, since the rule says standard library only and `jq` is a separate install. - The Ruby arm alone was told one of its brevity idioms is available. That is a thumb on the scale for Ruby, worth about 20 of its 1660 bytes. Nothing is counted until it is proven equivalent. Every implementation of a task runs against one reference and must produce the same bytes on stdout and the same digest for every file it leaves behind. Comparing the length of programs that do different things is meaningless, so that check gates everything: ```bash ruby src/run.rb text ``` ```plaintext t1_logs count requests and errors per path in an access log 53 impls identical t2_config rename one key across a tree of .env files, decoy key left alone 53 impls identical t3_rename renumber screenshot-N.png to zero-padded shot-NNNN.png 53 impls identical t4_csv filter a CSV to rows with stock, compute totals, write a CSV 53 impls identical EQUIVALENT: every implementation matches one reference (stdout + output tree) ``` ## The baseline: it writes Python Ten runs, same four specs, no language named anywhere. Five in the clean room, five with my real setup after the rule came out. The prompt is not blind, and I should say so. It asks for one sentence on why the agent chose what it chose, which tells it the choice is being watched. A blind version is the run I would do next. All ten wrote Python. Not one reached for Ruby, or bash, or JavaScript. The reasons they gave were about the standard library: preinstalled everywhere, handles line-terminator preservation and fixed-decimal formatting without dependencies. So the rule is not choosing between Ruby and some abstract field. It is displacing Python, every time. Five of those runs had my setup loaded and still chose Python, which is only worth reporting if the setup was genuinely in the room. It was. Asked directly, a session in that condition quotes my `CLAUDE.md` back at me, and the same setup moves the byte counts by up to 59% below. It was read. It simply has nothing left to say about language once the rule is out of it. That makes the cost question concrete, and the answer is not close: | bytes, four scripts, neutral prompt | Ruby | Python | bash | JS | |---|---:|---:|---:|---:| | source | **1660** | 3644 | 2333 | 3231 | | vs Ruby | 0% | +120% | +41% | +95% | Ruby is the shortest of the four, and in the clean room the agent's Python runs to more than twice the source for the same verified behaviour. That number is condition-dependent, and my own environment is much less flattering. Run it again with my real setup loaded and Python's lead over Ruby drops from 120% to 18%. What the rule buys you depends on what else is already shaping how your agent writes: | the rule's saving | unprompted default | told Ruby | cut | |---|---:|---:|---:| | clean room | 3595 | 1660 | **54%** | | my real environment | 1932 | 1375 | **29%** | Both rows are five runs against one, measured the same way. The clean-room row isolates the rule. The bottom row is where you actually are, if your agent is configured at all, and it is the number I would plan against. The counter drops comments and blank lines but keeps imports, since having to import is a real cost of the language. It also keeps Python docstrings, which is a point against Python that a `#` comment would not have cost it. Those are 8% of the clean-room Python total, and removing them leaves it 101% larger than Ruby instead of 120%. Nor is the gap all Ruby. Most of that 120% is not the language, it is what the agent wraps around it: the docstring, the `main()`, the `if __name__` guard, the line-ending bookkeeping. Discourage those habits and Python's lead falls to 18%, near the 36% I get writing both by hand. ## What the difference looks like One task, the config migration, as the neutral prompt produced it. Ruby first: ```ruby root = ARGV[0] Dir.glob(File.join(root, "conf", "*.env")).sort.each do |path| content = File.read(path) renamed = 0 rewritten = content.lines.map do |line| if line.start_with?("CACHE_TTL=") renamed += 1 "TTL_SECONDS=" + line[("CACHE_TTL=".length)..] else line end end.join File.write(path, rewritten) if renamed > 0 puts [File.basename(path), renamed].join("\t") end ``` That is the whole program. Read it once and you know it is right. Python's version of the same task runs to 38 lines. Here is the middle of it, the loop that does the work: ```python renamed = 0 lines = text.splitlines(keepends=True) for i, line in enumerate(lines): body = line.rstrip("\r\n") ending = line[len(body):] key, sep, value = body.partition("=") if sep and key == OLD_KEY: lines[i] = NEW_KEY + "=" + value + ending renamed += 1 ``` `text` is the file's contents; `OLD_KEY` and `NEW_KEY` are the two key names, defined at the top of the file. That is the same loop as the Ruby, plus manual line-ending bookkeeping, wrapped in a `main()` with a docstring, four imports and an `if __name__` guard. None of it is bad Python. It is just more of it, and the count agrees: | neutral prompt | Ruby | Python | bash | JS | |---|---:|---:|---:|---:| | lines | **56** | 108 | 101 | 89 | | distinct words | **104** | 155 | 125 | 118 | | longest line | 80 | 81 | **65** | 73 | | punctuation, share of non-space characters | **24%** | **24%** | 37% | 29% | Ruby wins the two that track reading effort, and loses longest-line to bash. I picked these four before running them and I report all four whichever way they fall, because there is no accepted way to measure readability and a metric chosen after the fact measures the author. ## bash only looks cheap when you ask it to be Told nothing, the agent writes careful bash: `shopt -s nullglob`, an explicit sort, a temp file per input, and a check for whether the original ended with a newline so it can put it back. That is 2333 bytes, 41% longer than Ruby. So I ran the neutral prompt a second time with one thing changed: `--safe-mode` off, so my real setup loads instead of the clean room. Same prompt, same specs, same fixture. | bytes, neutral prompt | Ruby | Python | bash | JS | |---|---:|---:|---:|---:| | clean room | **1660** | 3644 | 2333 | 3231 | | my real setup loaded | 1375 | 1627 | **945** | 2163 | | change | -17% | -55% | -59% | -33% | Every language shrinks, and the winner changes. In the clean room Ruby is shortest. Load my setup and bash is shortest by 31%, which is the tidy "just use bash" result, produced entirely by my own environment. I cannot pin that on one sentence, and should not try. Turning `--safe-mode` off restores my `CLAUDE.md`, skills, hooks and plugins at once, and one of those plugins injects a persona built around writing the shortest thing that works. The honest label on that row is "everything I normally run with". Both numbers are real. They answer different questions, and only one of them was the question I asked. ## How few words buy terse code If one line of configuration moves the numbers that far, what is the cheapest instruction that moves them on purpose? I ran a ladder: same specs, same clean room, one agent per language per rung, with only the instruction changing. | instruction | words | Ruby | Python | bash | JS | all | vs none | |---|---:|---:|---:|---:|---:|---:|---:| | (nothing) | 0 | 1660 | 3644 | 2333 | 3231 | 10868 | 0% | | "Be terse." | 2 | 1275 | 1830 | 906 | 2347 | 6358 | -41% | | "Golf it." | 2 | 735 | 1033 | 743 | 1369 | 3880 | **-64%** | | "Shortest code possible." | 3 | 799 | 1151 | 659 | 1448 | 4057 | -63% | | "Write the shortest X code possible. Minimise source length aggressively." | 10 | 697 | 1062 | 639 | 1322 | 3720 | -66% | | the same plus six explicit rules | 36 | 685 | 863 | 532 | 1243 | 3323 | -69% | Two words get you 64 of the 69 points available. The 34 words after them buy the last five, which at one run per cell is inside the noise: adjacent rungs swing by up to 11% per language, and the 2-word rung already beats the 3-word one. The words themselves matter far more than how many there are. "Be terse." and "Golf it." are both two words, and "Golf it." produces 39% less code overall, and less in every one of the four languages. "Golf" is a term of art, and it drags in everything the phrase "code golf" implies. "Terse" just asks politely. If you want an agent to write compact code, "Golf it." is the whole prompt. ## What terse code costs Here is that same config migration again, at the bottom of the ladder: ```ruby Dir[ARGV[0]+"/conf/*.env"].sort.each{n=0;File.write(it,File.read(it).gsub(/^CACHE_TTL=/){n+=1;"TTL_SECONDS="});puts [File.basename(it),n]*"\t"} ``` One line, 144 bytes against 409, and it passes the same byte-for-byte check. Three things in there need decoding: - `it` is Ruby's implicit block parameter, so each `it` is the current filename. It needs Ruby 3.4 or newer. On anything older this line is an error, not a slow read. - The `gsub` block both counts a match and returns the replacement, so `n` grows as a side effect of building the new text. - `[File.basename(it),n]*"\t"` is an array joined by a tab, because `*` on an array is `join`. I had to look twice, in my own language. The line counts collapse and the lines themselves get worse. Ruby's longest line goes from 80 characters to 151, JavaScript's from 73 to 199, and punctuation climbs from 24% of the non-space characters to 37%. You are not buying compact code. You are buying dense code, and paying in the thing the rule was adopted for. Then I pointed all 152 implementations at a directory with a space in its name, the six rungs plus the hand-written set as a control. One rung broke, and it is the expensive one: every bash script written under the 36-word instruction failed, all four, while the bash from every shorter rung survived. ```bash awk '{e[$7]+=$9>=400;t[$7]++}END{for(p in t)print p"\t"e[p]"\t"t[p]}' $1/logs/access.log|LC_ALL=C sort -t$'\t' -k2,2nr -k1,1 ``` That `$1` is unquoted. Three of the four exit 0 anyway, because a failing `awk` piped into `sort` reports the exit status of `sort`. Two of those three print nothing at all and the third prints `-1`. The error does reach stderr, so a person watching the terminal sees it. Anything checking only the exit status does not. So the last 34 words of instruction bought five percentage points of length and broke every bash script they touched. "Golf it." did not. ## The limits - Length is bytes. I did not run a tokenizer over any of these sets, so every percentage here is a byte percentage, and how closely it tracks a token bill is an assumption I have not tested. - One agent run per language per rung. The direction is consistent across four languages and six rungs. The exact percentages are not. - Four tasks, taken from the article's four categories so I could not pick favourable ground, but still four. - Ten runs is enough to say the default is Python here. It is not enough to put a number on how often. - The clean room removes configuration, not the model's own priors. "No config" is the honest floor I can reach, not a neutral universe, and a different model may default somewhere else entirely. - The spaced-path failure is one awkward path on one machine. It shows the failure mode, not a rate that transfers. ## What I would actually tell you Keep the rule. It wins on cost alone, which is not the argument its author made for it: against Python, the language your agent picks when you say nothing, it cuts source by about a third in a configured setup and by half in a bare one. Do not reach for a terseness instruction instead. Those cut more than the rule does, but they buy density, not brevity: less code that nobody can read, in a language you did not choose. Push far enough down that ladder and it broke four bash scripts on a path with a space, though "Golf it." itself did not. Override it in three places. When the library only exists elsewhere, which is Ghinda's own exception. When the script has to run where Ruby is not installed, which the baseline runs raised themselves by picking Python for being preinstalled everywhere. And when the job is one honest shell command, which the rule already exempts. Ghinda's own reason is still the better one, and it is the one no table here can settle. Reviewability is a fact about the reader. Those same numbers would hold for someone who cannot read Ruby at all, and for them every row above stops meaning anything. One thing carries past Ruby. Every number here moved, and two of them reversed, depending only on whether my own setup was loaded. If you benchmark an agent, take your config off first, or you are measuring your config. --- ## I wrote down 61 rules, then failed my own repos - URL: https://svyatov.com/blog/i-wrote-down-61-rules-then-failed-my-own-repos/ - Date: 2026-08-04 - Tags: opensource, ai, devops, showdev Nobody starts a library because they wanted to write a SECURITY.md. You start it because there is a thing you want to exist. Then you publish it, and a second job arrives that nobody signed up for: issue templates, a code of conduct, pinned action SHAs, a changelog that survives contact with a release, a publish job that does not leave a long-lived token lying around, and a README that still tells the truth eighteen months later. That is the boring half. It is mostly mechanical, and it decides whether a stranger with a good patch can figure out how to send it to you. So I wrote it down. [oss-kit](https://oss-kit.svyatov.com/) is 61 rules about that half of the job and nine agent skills that fix them. Then I pointed it at two repositories of my own. The first failed 27 rules. The second I had already put through the fixing loop, so it is the one that shows what is left at the other end. ## What the boring half contains Before you can hand the work off, somebody has to say what the work is. Seven areas: | Area | Rules | What it covers | |---|---|---| | Documentation | 10 | README order, claims that match the source, prose that is not marketing copy | | Community | 9 | License, contributing guide, code of conduct, security policy, issue forms, governance | | Continuous integration | 6 | What runs on push and on every change request, on which runtimes, and whether tests exist | | Security posture | 15 | Pinned action SHAs, workflow permissions, branch and tag rules, lockfiles, signed tags | | Release and publishing | 7 | Trusted publishing, provenance, approval gates, bills of materials | | Changelog and versioning | 7 | Keep a Changelog structure, the right bump, release notes that match | | Agent skills | 7 | Layout, frontmatter, licensing and portability, if your repo ships skills | Two areas are gated by a precondition rather than by a setting. Publishing needs a repository that ships a built artifact, and it then splits again: on the registry-push track every rule applies, and on the tag-published track, where the registry reads your forge and no publishing credential exists at all, four of the seven have nothing to attach to. Go modules and Packagist live on that second track. The agent-skills area needs a `SKILL.md` somewhere in the repo. That scoping is most of what an audit spends its time on. On the untouched repository below, 18 of the 61 rules came back not applicable, each with the reason: no skills, one principal holding every merge path, a release carrying no built asset, a package manager that gives you no way to decline dependency install code. That is how you tell a rule that does not reach you from one that quietly got dropped. On forges: 57 of the 61 rules score GitHub and GitLab alike. Three are GitHub-only, one is GitLab-only, and every rule states which. ## Why an agent needed a standard first A table like that is easy to write and useless on its own, which is the part I got wrong the first time. Ask an agent to improve your README and you get something plausible. It will be well-written. You will have no way to tell whether it is better, because "better" was never defined, and neither of you can point at anything. So every opinion in oss-kit lives in one file as a numbered rule, and every rule carries a line naming the evidence you can go look at. Not "the README should be welcoming" but: the first paragraph after the title is a single sentence naming what the project is, and it appears before any table of contents or badge row. That is a claim you can go and check for yourself, and tell me I am wrong about. "Welcoming" is not. The same discipline is what makes the kit reach past the language I happen to write in. Eleven ecosystems get a real answer rather than a footnote: npm, PyPI, RubyGems, crates.io, Go modules, Packagist, NuGet, Maven Central, Hex, pub.dev, and container images. Seven of the nine skills carry one file per ecosystem, 77 files in total, each ending with the date its source was last read. A script fails CI on a missing file, a file no roster lists, a declared heading left empty, or a date that does not parse. Whether a library commits a lockfile is not one question with one answer, so the files answer it per ecosystem, each citing the documentation that settles it. This is also the honest answer to "why not just use OpenSSF Scorecard." Scorecard is good and I use its data, but it is security-scoped: branch protection, pinned dependencies, code review, fuzzing. It has no opinion about your README, your changelog, or whether a contributor can find out how to run your tests. CNCF's [CLOMonitor](https://github.com/cncf/clomonitor) does have those opinions, and it is the closest thing to this that already exists. It scores documentation, community files, licensing and security posture against a public checklist. It is also a hosted dashboard aimed at foundation-hosted projects, it does not read GitLab, and it stops at the report. Nothing in it hands a finding to the thing that fixes it. ## What you actually get `clsx-ruby` is a gem of mine: green CI, published to RubyGems, six releases, and I would have told you it was in decent shape. I audited it a week ago, fixed none of what it found, and let exactly one commit land since, a development-dependency bump. So the report below is that same repository, untouched. ```bash cd clsx-ruby npx skills add svyatov/oss-kit --skill '*' ``` Then, to the agent: *Audit this repository against the oss-kit standard.* Sixty-one verdict lines came back: 16 pass, 27 fail, 0 unknown, 18 not applicable. Every fail carries the evidence it read and the skill that owns the fix. Three of them, verbatim, with the `Check:` text each one quotes cut for length: ```text - R-COM-04 fail no `SECURITY.md` at the repository root, in `.github/`, or in `docs/` Fixed by: oss-community - R-SEC-11 fail rubygems: `dependency-graph/sbom` lists 11 packages, every one a direct `Gemfile` entry, plus the 3 actions; the on-disk `Gemfile.lock` resolves 29 gems, so the 18 transitive dependencies are watched by nothing, because no lockfile is committed for the graph to read. `vulnerability-alerts` answers 204, so the alerting itself is enabled Fixed by: oss-harden - R-PUB-03 fail rubygems: `https://rubygems.org/api/v1/attestations/clsx-ruby-1.2.0.json` answers 200 with an empty array, so the registry serves no attestation for the exact published version Fixed by: oss-publish ``` A few of the twenty-seven, in the order that they bother me: **Nobody can report a vulnerability in this gem privately.** There is no SECURITY.md, so a person who finds something either opens a public issue describing it or gives up. **Eighteen of the twenty-nine gems it resolves are watched by nothing.** The dependency graph reads the `Gemfile`, the `Gemfile.lock` is in `.gitignore`, so everything transitive is invisible to the one tool that would tell me about an advisory. **Three of its actions are pinned to a tag rather than a commit.** `actions/checkout@v4`, `ruby/setup-ruby@v1` and `codecov/codecov-action@v5`, each a name whoever publishes it can repoint whenever they like. **The README opens with "The fastest".** There is a benchmark table that backs that up, 55 lines down, past the point where a reader decides. A superlative with its evidence out of reach is the exact thing I wrote a rule against, in a README I wrote myself. **The published gem has no attestation.** Nothing ties `clsx-ruby-1.2.0.gem` back to the commit it was built from. The audit did not conclude that from a 404, which is the difference between a fail and an honest `unknown`: a guessed URL answering 404 proves nothing about the gem. The report is a file now, `oss-audit-report.md`, written at the root of the repo and untracked. It carries a verdict line for all 61 rules, passes included, and it ends by grouping the 27 fails into seven pull requests with the dependencies between them spelled out. Community files first, because SECURITY.md is what the security rules build on. Commit the lockfile before the rule that reads the dependency graph, because one closes the other. Publishing last, because two of its rules can only be verified against a newly published artifact. ## Then you fix them None of that is work that gets done by reading a report, which is what the other repository is for. `sec_id` is a gem I have maintained for years: 17 published releases, every community file present, contributing guide, code of conduct, security policy, issue templates. When I first ran this audit on it, against a standard that held 46 rules, it scored 19 pass, 18 fail, and one honest `unknown`. Then I ran the fixing loop on that report. Eight pull requests, which I grouped by owning skill myself, because the report file did not exist yet: pin the actions and commit the lockfiles, publish through trusted publishing, state the governance, give the README a differentiator, resolve the changelog version links. Same prompt, same repo, seven days and 61 rules later: ```bash cd ../sec_id ``` ```text Audited 51 applicable rules: 44 pass, 7 fail, 0 unknown, 10 not applicable. ``` Eighteen fails to seven, while the standard grew by fifteen rules underneath it. The `unknown` closed too, and on real evidence: the sigstore bundle's digest matches the published gem's checksum, and the certificate names the workflow and the tag it was built from. The standard moving did not only cost me. `R-COM-06` wanted a CODEOWNERS file and `sec_id` failed it on the first run. It now scores not applicable, because the rule gained an exclusion for a repository where one principal holds every merge path. No file was ever written. Some of the drop from eighteen to seven is the rule moving rather than the repo. The seven survivors are what a fixing pass could not close. Two are rules that did not exist when I fixed it, and the next section is about them. Two are failures the fixing caused: one pull request added a `SKILL.md`, which pulled the whole agent-skills area into scope, and two of its seven rules fail. One is a rule whose text changed under a config I never touched, and one is a check I think is simply wrong. Those two get the sections after that. The seventh is the one I would call plain old debt. `R-CHG-05` wants a removal to have been deprecated in some earlier release, and two of `sec_id`'s major versions removed things that never were. Both are published, so nothing can go back and deprecate them now. The contributing guide already states the gap outright, which is about as honest as that gets. Fixing a repository is how you find the rules that were never reaching it. ## The standard moves under you Fifteen rules in seven days, and both repositories fail the same two new ones. `R-SEC-14` asks your dependency updater to wait before proposing a version published minutes ago, through Dependabot's `cooldown` or Renovate's `minimumReleaseAge`. `R-SEC-13` asks for a ruleset over `refs/tags/*` that blocks tag updates and deletions and names who may create one. Both repos guard their default branch, neither guards a tag, so a released version number can still be repointed at a different commit. That is the one change a version number exists to make visible. The cooldown rule is the one I would have defended hardest, so here is what writing this post did to it. The argument goes: what ends a registry compromise is other people looking, and that takes hours. An updater with no cooldown opens its pull request inside that window, so the project that merges its bumps promptly is the one that installs the bad version first. Diligence becomes the exposure. Both my repos fail on a Dependabot config with no `cooldown` block, which is a fair reading of the check. But GitHub [applies a default cooldown of three days](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference) to version updates when you have configured none, and three days outlasts the window the rule was written about. The exposure I just described is not present in either repository. Renovate is where it survives. Its `minimumReleaseAge` [defaults to `null`](https://docs.renovatebot.com/renovate-schema.json), so a Renovate repo with nothing set waits zero days. Same rule, same fail, two situations that are not remotely alike, and the rule text cannot tell you which one you are in. I have [filed that against my own standard](https://github.com/svyatov/oss-kit/issues/69). What is left of the rule is still worth having, and it is a narrower thing than I wrote down: a written setting does not move when the platform changes its default, and it is a decision somebody can audit. ```yaml # .github/dependabot.yml version: 2 updates: - package-ecosystem: "bundler" directory: "/" schedule: interval: "weekly" cooldown: default-days: 7 semver-patch-days: 3 ``` That is the whole fix, and both of my repos still do not have it. A third new rule reaches neither repository and is the one I would read first. `R-SEC-15` asks CI to install dependencies without running the code they ship. That is the step the September 2025 npm worm used to spread. [Unit 42's writeup](https://unit42.paloaltonetworks.com/npm-supply-chain-attack/) records that the malicious versions "contain a worm that executes a post-installation script." Installing was enough. It falls outside eight of the eleven ecosystems rather than failing them, RubyGems among them, which is why both gems score it not applicable. Cargo, RubyGems and Hex give you no documented way to decline. Maven, NuGet, Go modules, container images and pub.dev run nothing during resolution at all. There is a cost to writing rules this fast, and one of `sec_id`'s seven fails is it. `R-CI-01` scores a trigger block that has not changed since February. What changed is the rule: a `pull_request` trigger carrying a `branches:` filter now fails where it used to pass. The project is below 1.0.0, so an incompatible change ships in a minor release, and a repo that passed yesterday can fail today. ## What it will not do The rules are the part you can argue with. The scoring is the part I would argue with. Five rules ship with a real checker, a dependency-free script that either exits 0 or does not. The other 56 are scored by a model reading a check line. That ratio has moved the wrong way: the standard grew by fifteen rules and the checker still covers the same five. The kit did gain five scripts in that time, and not one of them scores a rule. They collect the facts a check line refers to. The one script that returns a verdict is the one it already shipped with. A collector can also be wrong. On `sec_id`, the bundled one reported two CI jobs where the repository has seven, with a `steps: 0` beside each as the tell. The rule it fed passes either way. An audit that filtered on that output would have scored a five-job blind spot without noticing. The model half is worse. One check asks that every code block name the file or tool it goes to. `sec_id`'s README fails that on roughly 35 REPL-style blocks under a literal reading, and passes under the intent reading. A check that would fail essentially every library README ever written is telling you about the check, not the README. Another rule passed on judgement while the bundled validator exits 1, because counting it would have reported one gap twice. Then there is the one I did not see coming. The kit added a closing step that re-audits after the fixes and diffs the two reports, so a fix that broke something else surfaces as a verdict that went from pass to fail. I could not run it. The first audit predated the report file, so its verdicts were chat output and nothing else. A verdict nobody wrote down cannot be compared, and my own repo is the worked example. ## The nine skills | Skill | What it does | |---|---| | `oss-audit` | Scores the repository and routes each gap to a skill. | | `oss-community` | Writes every community file, from the license to issue forms. | | `oss-readme` | Orders the README and checks its claims against the source. | | `oss-ci` | Writes the test, lint, and build jobs for either forge. | | `oss-harden` | Pins action SHAs, trims permissions, and guards branches and tags. | | `oss-publish` | Publishes to eleven ecosystems, gates the run, and signs it. | | `oss-changelog` | Keeps CHANGELOG.md, picks the bump, writes release notes. | | `oss-writing` | Fixes the sentences in commits, reviews, docs, and issues. | | `oss-skill` | Fixes the structure and portability of the skills you ship. | What these skills actually do is refuse things, and the refusals are why I let them near my repositories at all. (These are design commitments written into the skills, not behavior this post tested end to end.) The missing SECURITY.md goes to `oss-community`, which will not write `security@example.com`, or any plausible-looking address nobody confirmed, and will not promise a response window you never agreed to. If the repo does not tell it where security reports should land, it stops and asks me. It also prefers GitHub issue forms over Markdown templates, because a template made of Markdown headings cannot require a field, so a contributor can delete every heading and submit an empty issue. The README's out-of-reach superlative goes to `oss-readme`, which matches every claim in a README against the manifest, the source and the CI config. It also will not pick your README's facts for you: it sweeps the repo, sorts candidates into the questions a reader has, lists what it rejected and why, then stops and makes you choose three to five. Left alone, a writer picks whatever the source tree makes easy, which is how a facts list ends up describing how a project is built instead of what it does. The three actions pinned to mutable tags go to `oss-harden`, which pins them to full commit SHAs. What it will not do is pin a dependency whose origin it could not establish in the first place. Pinning gives you the same unverified code at a known revision, and the next person to read that line will assume somebody vouched for it. It reports that as an observation with no rule ID attached, because no rule reaches it. The unattested gem goes to `oss-publish`, which moves publishing into a workflow that authenticates without a stored token. It will not fake a missing approval gate with some third-party action it found; it reports the rule as unmet and says so. `oss-writing` is the one I use before writing anything at all. It gives a commit or a pull request a body only when one of six named triggers applies, and the default is no body. It also refuses to add `Co-Authored-By: Claude` trailers, on the grounds that a trailer records who is accountable for a change and a tool cannot be. ## The rules you will argue with All of which assumes you accept the rules doing the routing. I am not going to tell you these are 61 uncontroversial best practices, because several of them are not. The README rule puts your badge row *below* the opening sentence. PostCSS and Nano ID put badges above, and they are more successful projects than anything I have written. The skill concedes the divergence in writing and states the condition under which it holds. The prose rule bans every emoji character in project documentation. I argued against my own rule on this one, wrote "banning emojis in open source might be way too strict, emojis are fun," and then never changed it. Two of the agent-skill rules are deliberately stricter than the Agent Skills specification. The spec permits Python, Bash and JavaScript in a bundled script and leaves the choice to the implementation; oss-kit allows only `sh` or dependency-free Node. The spec marks the `license:` field optional; oss-kit requires it, because an installer may extract one skill directory without your repository's license file. That second one is a rule `sec_id` now fails, which is how I know it bites. And the versioning rule overrides SemVer during `0.y.z`, using MINOR for incompatible changes rather than forcing a premature 1.0.0. You can read every rule, with its reasoning and its check, [without installing anything](https://oss-kit.svyatov.com/standard/). That is deliberate. Disagreeing with rule R-DOC-05 by name is a better outcome than nodding along to a prompt you never read, and there is a rule-proposal issue form for doing something about it. ## Where to start Install the whole kit: ```bash npx skills add svyatov/oss-kit --skill '*' ``` Or one skill at a time, if you only want the README one: ```bash npx skills add svyatov/oss-kit --skill oss-readme ``` In Claude Code or GitHub Copilot CLI, type these two at the prompt instead: ```text /plugin marketplace add svyatov/oss-kit /plugin install oss-kit@oss-kit ``` Nine hosts are recorded, each with the paths it reads and the date that was checked. Two of them have no command-line install at all, so placing the directory is the install. Then ask your agent: ```text Audit this repository against the oss-kit standard. ``` Authenticate `gh` before you do, because a checkout cannot answer what the audit needs to score. Rulesets, environments, the dependency graph and release bodies are all forge reads. Without them those rules come back `unknown` rather than wrong, which is the correct answer and a much thinner report. Read the report, then run whichever skill each line named. The audit changes nothing it scores; it writes one file. The skills do change things, and they are not silent about it: they stop and ask when a file needs a fact your repository does not contain, they propose forge settings rather than changing them under you, and they finish by listing every file written or proposed and every fact that came from asking rather than reading. Skills install independently, so you can take one and ignore the rest. If the repo is brand new there is nothing to score yet, so skip the audit and go in order: `oss-community` for the license and community files, `oss-readme`, `oss-ci`, `oss-harden`, `oss-changelog`, then `oss-publish` if you ship a package. Run it on something you already maintain. Not a toy repo, the one you would be embarrassed to have someone read. You will get a list. Some of it you will disagree with. The rest is the boring half, finally written down, in an order somebody thought about. Then hand it to the agent, because you did not start this project to write a SECURITY.md. --- ## Kubernetes earned its security badge in 2017 and never came back - URL: https://svyatov.com/blog/kubernetes-earned-its-security-badge-in-2017-and-never-came-back/ - Date: 2026-07-31 - Tags: opensource, security, devops, ruby Kubernetes has an [OpenSSF Best Practices badge](https://www.bestpractices.dev/projects/569). It earned that badge on 16 August 2017 at 14:52:28 UTC, and nobody has touched the entry since. The save that earned it is still the last anyone made: the two timestamps sit three milliseconds apart, because one save wrote both. The badge on that page today looks exactly like a badge earned this morning. It carries no date. [bestpractices.dev](https://www.bestpractices.dev/) has been running for a decade, the CNCF requires it before a project can graduate, and it had never crossed my desk. So I went and read it properly: the criteria, the [Rails app behind it](https://github.com/ossf/best-practices-badge), and the daily statistics it has been publishing at a public URL the whole time. This is what I found, including the part the program's own maintainer raised in 2024 and nobody has fixed. Every number here was fetched on 31 July 2026, by crawling the site's own JSON API and its published daily statistics. They move daily, so check them rather than trusting mine. ## What the thing is It is a questionnaire. You answer a list of questions about how your project is run, and if you answer enough of them the site gives you a badge image for your README. It is free, it takes no review board, and it works for any project anywhere. The Linux kernel's entry points at git.kernel.org. GitLab's own repository holds one. Working anywhere is the badge's real advantage over the automated scanners. There are [two ladders](https://openssf.org/blog/2026/02/25/getting-an-openssf-baseline-badge-with-the-best-practices-badge-system/) now, which is the first confusing thing a newcomer meets: ```text METAL (2016) BASELINE (2026) passing 67 criteria baseline-1 24 controls \ | baseline-2 19 more > OpenSSF Baseline, silver 55 more baseline-3 21 more / MUST-only controls | gold 23 more 3,080 projects at passing 223 at baseline-1 262 at silver or better 103 at baseline-2 86 at gold 44 at baseline-3 ``` Same form, same login, two unrelated series of questions. The metal ladder is cumulative: a gold badge is 145 criteria deep. Anyone with an account can create an entry for any project, and nobody checks that you own it. The first person to file owns it, though GitHub committers on the repository you name can edit it too. ## Where it came from Heartbleed, April 2014. Two weeks after the bug went public the Linux Foundation announced the Core Infrastructure Initiative, and the badge was one of the things that initiative produced. The repository's first commit is dated 22 July 2015. Dan Kohn, two files, 24 lines: an MIT license and a README containing nothing but the project's name. Two weeks later David A. Wheeler pushed the first draft of the criteria, and the document says out loud what the thing was always going to be: > The goal is to eventually create a "badging" program where OSS projects that meet the criteria can voluntarily self-certify that they meet the criteria and then be able to show a badge. Self-certify. That was the plan on day one, and it is still the plan. Greg Kroah-Hartman opened the [first pull request](https://github.com/ossf/best-practices-badge/pull/1) on 10 August 2015 to delete the code-coverage requirement, arguing coverage "is not a good metric for any sort of assurance other than someone wrote a bunch of tests." It was closed without merging. Eleven days later somebody opened the exact opposite pull request, asking to add coverage back. The badge went generally available in May 2016. The announcement carries a line that has aged well: > Prior to Heartbleed, OpenSSL failed to meet more than one-third of the CII Best Practices Badge criteria. Today it meets 100 percent. Then CII became the OpenSSF, and in August 2023 the site moved from bestpractices.coreinfrastructure.org to bestpractices.dev, which is why old badge links point at a domain that no longer names anything. OpenSSL, ten years on, still holds passing and nothing above it. ## What the 67 questions actually ask The [range](https://www.bestpractices.dev/en/criteria) is wider than "do you have a license." The 67 sort into six groups, and the split says something before you read a single one: Basics 13, Change Control 9, Reporting 8, Quality 13, Security 16, Analysis 8. Most of the form is asking how you run the project. Four of them, verbatim. The easy one: > The project sites (website, repository, and download URLs) MUST support HTTPS using TLS. The one you cannot fake with a config change: > The project MUST have at least one primary developer who knows how to design secure software. The one that is true or false about the world, not about your repository: > There MUST be no unpatched vulnerabilities of medium or higher severity that have been publicly known for more than 60 days. And the one that quietly locks a whole class of project out of gold: > The project MUST have a "bus factor" of 2 or more. That last one is a gold MUST and a silver SHOULD. If you maintain your project alone, silver is reachable by writing a justification and gold is not reachable at all, no matter how good the code is. Gold also wants at least two unassociated significant contributors and half of all changes reviewed by someone other than their author. Gold is measuring your staffing, not your software. Answering "Met" is sometimes not enough. Across all 145 criteria, 52 require a written justification and 34 require a URL inside it, and an answer that misses either is dropped from your percentage. That burden is almost entirely a silver and gold problem, though: at passing level it is one justification and eight URLs. Passing is lenient in the other direction too. An unmet SUGGESTED criterion still counts toward your score, so a SUGGESTED item only has to be answered rather than met. And where a justification is required, the bar is `MIN_SHOULD_LENGTH = 5`. Five characters. There is also an undocumented convention: a justification beginning with `// ` is treated as a comment rather than an answer, and it appears nowhere in the docs or the interface strings. How long does it take? The one clean public figure comes from [Marc Wrobel](https://github.com/keycloak/keycloak/discussions/13276#discussioncomment-3464477), who filled one in for his own library and said it took "3 to 6 hours to answer all the questions." [Roscoe Bartlett](https://ideas-productivity.org/events/hpcbp-093-openssf), teaching the badge to scientific-computing groups at Sandia, puts reading the criteria alone at more than half a day. The Linux Foundation's 2016 press release claimed "generally, in under an hour," which I can find no evidence for. Sandia's FIREWHEEL went from entry creation to passing in six hours and two minutes, one sitting. BizHawk opened its entry in November 2021 and is still in progress. You do not have to type everything. The site reads your repository and pre-fills what it can, and you can hand it a `.bestpractices.json` file or a `security-insights.yml` in the repo instead. Autofill only works against GitHub. ## Does anyone actually check? The maintainers answer this themselves, in [the repository](https://github.com/ossf/best-practices-badge/blob/main/docs/vetting.md), and their answer is more careful than most of the criticism I found: > That means that the badge is not strictly self-certification, instead, the badge is merely based on it. I went to find out how much work "merely" is doing. The app runs a set of classes it calls detectives, which read your repository and propose answers. Most of them only fill in blanks. Three of them can overrule a human being who claimed "Met", across five criteria: the HTTPS check, the security-headers check, and the license-location check. Three, and only on GitHub. The license check reads a file listing the app can fetch from nowhere else, so on GitLab or a self-hosted repo the referee is two checks over three criteria. It also runs the other way, which surprised me. Five answers get forced *to* Met over whatever the human said, including the license checks. The bigger check is social rather than automated, and the maintainers lean on it deliberately: every answer and every justification is published on the project page. That is how I found the dead URLs later in this post. Anyone can read what a project claimed and go and look. And the detectives only wake up when someone saves the form, or opens it with an explicit `?reanalyze`. Merely looking at a completed entry runs nothing. So what happens when somebody disputes a badge? There is one good test case: in August 2024 a contributor [filed an issue](https://github.com/ossf/best-practices-badge/issues/2153) saying Netdata should not hold a badge, because it had begun shipping closed-source dashboard blobs that Debian, Alpine and Fedora had all refused. Wheeler's first response was to check the LICENSE file, see GPL-3.0, and call it settled. Three days later he wrote: > I can point to myself; when this issue was first raised, I went to LICENSE, saw "GPL-3.0", and said "sure, that's OSS". He escalated it to the project mailing list. Nobody replied. The issue is still open two years later, and Netdata's entry still shows a passing badge, last edited in May 2023. That is not fraud. It is a volunteer dispute process with one person in it. ## The clock that isn't there Here is the funnel, from the site's own daily statistics: | where entries sit today | entries | share | |---|---|---| | registered an entry | 11,434 | 100% | | at 25% or more | 5,785 | 50.6% | | at 50% or more | 5,026 | 44.0% | | at 75% or more | 4,529 | 39.6% | | at 90% or more | 3,863 | 33.8% | | at passing | 3,080 | 26.9% | | at silver or better | 262 | 2.3% | | at gold | 86 | 0.8% | Those are positions today, not high-water marks, so entries that slipped back are counted where they now sit. Finishing at 26.9% is healthier than the program itself advertises: the repository's README has said "on average only about 10% of pursuing projects have a passing badge" since June 2017, when it was accurate to a tenth of a point. The line has not been edited since. Now the interesting half. Of the 3,082 entries holding a passing badge (a live crawl, two ahead of the previous night's statistics row above), 1,806 have never been edited since the write that earned it. Not "not edited recently." | gap between earning the badge and the last edit | entries | share | |---|---|---| | same write (under 100 ms) | 1,806 | 58.6% | | 100 ms to 1 s | 0 | 0.0% | | 1 s to 1 min | 38 | 1.2% | | 1 min to 1 h | 340 | 11.0% | | 1 h to 6 h | 100 | 3.2% | | 6 h to 24 h | 99 | 3.2% | | more than 24 h | 697 | 22.6% | | not classified (two backfill artifacts) | 2 | 0.1% | Nothing at all falls between 100 milliseconds and one second, so the top bucket is a category rather than a cutoff I chose: one save, with the skew inside it running from 0 to 48 milliseconds. One caveat on that 58.6%, since it flatters the argument: a third of those entries first passed in 2026 and have barely had the chance to come back. Restrict it to badges earned three or more years ago and it is still 53.6%. Meanwhile 57.8% of passing entries have gone untouched for a year or more, and 15.5% for five years or more. There is no expiry. I looked for one: the scheduled jobs are a statistics task and a reminder mailer, neither recomputes criteria, the recurring-jobs config is an empty stub, and no CI cron touches badges. While a project sits at 100% the main reminder query skips it, but "never emailed again" would be too strong. Drop below 100% and you re-enter the queue after a 30-day grace, which has happened to 49 entries since they first passed, GitLab and Syncthing among them. A separate warning mailer does reach projects still at 100%: ten were queued the day I looked. Kubernetes got its last reminder on 15 June 2017. It earned the badge two months later, and nothing has emailed it since. ### But are the old answers actually wrong? "Old" and "wrong" are different words. If a project's practices did not change, its answers did not need editing. For the famous stale entries, that defence holds. Lynis has not touched its entry since May 2016 and its repository was pushed to this morning. POCO and cjdns are both still alive, and the specific URLs their justifications point at still resolve. But the decay is measurable. I resolved every hostname in every passing entry's repository and homepage URLs: | entry last touched | entries | dead hosts | share | |---|---|---|---| | under 1 year | 1,301 | 3 | 0.23% | | 1 to 3 years | 860 | 5 | 0.58% | | 3 to 5 years | 444 | 7 | 1.58% | | 5 years or more | 477 | 8 | 1.68% | That is 23 dead hosts across the whole passing set, so read the shape rather than the multiple: single-digit counts per cohort, and moving two entries would break the monotonicity. Opus claims a repository at a host that no longer exists. GnuPG's vulnerability-reporting URL times out. Scraps has had no commits since 2020 and still shows `maintained` as Met, which is an answer it never gave: that criterion arrived in 2021, five years after its last save. Staleness is not the only route in, either. One entry edited the day before I looked points its homepage at a host that does not resolve, and another holds passing with a `repo_url` that is a dead link to a foundation page rather than a repository. The sharper failure in that table is not decay. Five entries serve a passing badge while claiming `sites_https` is Met with an `http://` URL, which is the exact example the maintainers' own documentation gives of a claim the app will not accept. None of them has been edited since 2016, so those answers were wrong when they were saved rather than rotting later. The check that would strip them today was written in April 2016, before all five saves, but I could not confirm from the commit history whether it was wired into the save path by then. It is also three people rather than five: one of them filed three near-identical entries thirty-three seconds apart. One thing does re-check you, and it happens without you. When the maintainers change a criterion, a bulk task re-scores every project's stored answers against the new rules, and it writes with `touch: false`, so your `updated_at` never moves. On 11 April 2021 nine projects lost their passing badge inside a 72-second window. Two of them had not been touched by their owners since 2016 and 2017. So revocation exists, and it fires when the maintainers change a criterion. Nothing fires when a project simply goes quiet. ## The maintainer already said all this In March 2024 somebody [opened an issue](https://github.com/ossf/best-practices-badge/issues/2117) pointing out that dead projects sit in the badge table looking healthy. Wheeler replied: > Also: We do need a way to withdraw badges if no one's checked it in a long time. The "obvious" way to do it is to add a passing criteria like "badge answers have been validated within the last 3 years by a badge applicant". That means every 3 years someone the badge will drop unless someone does something. The reporter agreed it was a good idea. Then nothing was built. The issue is still open, the roadmap has no expiry item, and it opens by describing the project as "essentially in a 'sustainment' mode." One related mechanism did ship, in 2021: a new criterion reading "The project MUST be maintained," added outside the usual yearly cycle. The working-group minutes explain the design choice plainly: > it doesn't risk existing badges because the default value is 'Met' The criterion that exists to catch abandoned projects defaults to claiming they are fine, and the automatic detection Wheeler sketched alongside it was never implemented. The program diagnosed itself correctly, wrote the roadmap entry calling itself sustainment mode, and has not built the fix. ## Who comes back The write-once pattern is not uniform, and the split is sharper than I expected. | top tier reached | entries | last edit within a day of earning | median gap | |---|---|---|---| | passing only | 2,820 | 2,278 (80.8%) | 0 days | | silver, not gold | 176 | 78 (44.3%) | 3 days | | gold | 86 | 29 (33.7%) | 48 days | The tier a project chases tracks whether it comes back, and I do not think that is virtue. Gold's gates are staffing gates, so gold holders are by definition projects with more than one person available to do the coming back. Forty-four entries have been edited more than three years after earning passing and also within the last year. The long-horizon group names itself: curl, the badge site's own app, the Linux kernel, GitLab, OpenSSL, Weblate, Jaeger. curl first passed in March 2016 and last edited in May 2026, ten years apart. ## Who requires it, and does that work? The [CNCF requires a passing badge](https://github.com/cncf/toc/blob/main/.github/ISSUE_TEMPLATE/template-graduation-application.md) for both incubation and graduation. The Academy Software Foundation, LF AI & Data, LF Energy and FINOS each set their own rung. Then reality. Two CNCF incubating projects have no badge entry at all. Kubeflow's umbrella entry sits at 88%, below passing. Not one graduated Academy Software Foundation project displays gold, although that one is unfair to score: their rule is gold-minus-ten-exemptions, and the site has no way to show that variant, so those projects correctly display passing. A mandate gets you an entry. It does not get you a maintained one. ## Which ladder, and where Scorecard fits Most people who have heard of any of this are thinking of [OpenSSF Scorecard](https://github.com/ossf/scorecard), which is a different tool: it scans your repository and gives you a score out of ten without asking you anything. I picked ten projects to see how far apart the two can get, so read this as an existence proof rather than a correlation: | project | badge | badge updated | Scorecard | scanned | |---|---|---|---|---| | curl/curl | gold | 2026-05-13 | 6.9 | 2022-11-09 | | kubernetes/kubernetes | passing | 2017-08-16 | 7.6 | 2026-07-27 | | rails/rails | in progress, 94% | 2020-10-15 | 6.3 | 2026-07-27 | | nodejs/node | passing | 2024-05-07 | 6.1 | 2026-07-31 | | facebook/react | in progress, 81% | 2018-02-19 | 7.0 | 2026-07-27 | | ossf/best-practices-badge | gold | 2026-07-18 | 8.0 | 2026-07-31 | | ossf/scorecard | passing | 2023-09-19 | 8.7 | 2026-07-25 | | thephpleague/commonmark | gold | 2019-06-20 | 5.1 | 2026-07-27 | | daurnimator/lua-http | passing | 2018-08-26 | 2.7 | 2026-07-27 | | FoveaCentral/google_maps_geocoder | passing | 2024-11-12 | 8.4 | 2026-07-30 | Scorecard last looked at curl in November 2022 and re-scanned most of the others this week. commonmark holds gold on every tier and scores 5.1. React has no badge worth speaking of and scores 7.0. The disagreement runs both ways, which is the point. The two tools are not independent: Scorecard includes your badge as one of its own checks. It fetches bestpractices.dev directly. But it is a low-weighted check, and removing it entirely moved these ten scores by between 0.0 and 0.3. The clearest writing I found on either tool is the maintainers' [own comparison](https://github.com/ossf/best-practices-badge/blob/main/docs/badge-vs-scorecards.md), which concedes both sides: > Scorecards: This is *entirely* automated. Pros: You can evaluate *any* OSS project with it, immediately. Cons: It focuses on what can be automatically measured (not necessarily what's important...) > Best practices badge: this requires projects to fill in a form. Pros: It tries to focus on what's important (not what's easily automated); it can handle arbitrary situations & hosting platforms. Cons: It requires projects to work with it. Scorecard can tell you whether branch protection is on, which no questionnaire can verify. The badge can ask whether you fix medium-severity vulnerabilities within 60 days, which no scanner can observe. Scorecard also re-runs itself, in principle: its published data for curl is from November 2022, so automated is not the same as current either. If you are starting today: the metal ladder if you want the full interrogation, Baseline if you want the MUST-only subset that foundations are beginning to reference. FINOS already mandates Baseline rather than the metal ladder. ## The Ruby corner I went looking for my own ecosystem and it is thin. 105 entries list Ruby as their primary language: 1 gold, 1 silver, 18 passing, 85 still in progress. The single Ruby gold is BadgeApp, the badge site itself. A Rails application, it holds gold on every tier including all three Baseline levels, and it is the only Ruby project on that list I would call well known. Rails opened an entry in November 2015. It sits at 94%, has never earned the badge, and was last touched in October 2020. Ruby itself sits at 16%, edited exactly once, the day after the entry was created. No entry at all for rubygems, rspec, rubocop, sidekiq, puma, devise, jekyll, rack, sinatra, hanami, or anything under hotwired. If you maintain a Ruby library and want a genuinely uncrowded thing to do this weekend, there it is. ## Does any of it make software safer? No study has measured badge status against security outcomes, and I went looking through the obvious places: Scholar, arXiv, the OpenSSF's own writing, and the foundation reports that track this sort of thing. [The paper people reach for](https://arxiv.org/abs/2210.14884) studies OpenSSF Scorecard rather than the badge, on 2,422 npm and PyPI packages, and its headline finding points the opposite way from how it gets summarised: vulnerability counts went *up* as the aggregate security score went up, at an R-squared of 0.04. There is a paper often cited as an independent study of the badge criteria. It turns out to be the text of a 2016 LWN article. Only 16 of the 67 passing criteria are security criteria. The rest are about whether the project is run in a way a stranger can participate in. So: the badge measures whether you did a specific set of sensible things once. Whether that makes your software safer is an open question that ten years of data has not been pointed at. ## How to read one, and whether to get one Read the date before you read the level. It is on the project page, and the badge image will never tell you. You can check any project in one line: ```bash curl -sL 'https://www.bestpractices.dev/projects.json?url=https://github.com/kubernetes/kubernetes' \ | jq -r '.[] | "\(.name): \(.badge_level), last updated \(.updated_at[0:10])"' ``` ```text Kubernetes: passing, last updated 2017-08-16 ``` The `-L` matters: the API redirects to a URL-encoded form of your query, and without it you get an empty response and no error. Two readers should skip it. If you want a signal that a project is healthy today, this is not that, and nothing on the site is. And if you are alone on your project, know where the ceiling is before you spend the day: silver costs you a written justification, and gold is closed to you outright. The Baseline ladder has no such gate, which is one practical reason to prefer it. For everyone else, the honest case for filling one in is not the image. It is the questions. Ten years of public argument went into choosing them, the first pull request against them was from Greg Kroah-Hartman, and answering them costs a day if you go by the one maintainer who timed it. The badge at the end is a receipt for that day and nothing more. Which is fine, as long as you read it as one. Just put the re-check in your own calendar. The site will not send you one. --- ## Rails already ships class_names. I built clsx anyway. - URL: https://svyatov.com/blog/rails-already-ships-classnames-i-built-clsx-anyway/ - Date: 2026-07-21 - Tags: rails, ruby, tailwindcss, webdev When I published a little gem for conditional CSS classes two years ago, the first comment was Adrien Poly asking the obvious thing: "What is the main difference with rails class_names helper?" My honest reply at the time: I didn't know `class_names` existed. I had written a gem for something Rails already shipped. So I went and looked, guessed the difference was performance, and left it there. That answer bugged me for two years. Here is the real one. `class_names` is a good view helper. It also only ships with ActionView, it spills a few inputs, it is slower than it needs to be, and it has no idea that `px-2` and `px-4` are the same knob. None of those matter until they do. When they did, for me, the fix turned one small Rails gem into two: [clsx-ruby](https://github.com/svyatov/clsx-ruby), a framework-agnostic core, and [clsx-rails](https://github.com/svyatov/clsx-rails), a thin adapter over it. This is the tour I wish I could have given Adrien in that comment thread. ## First, credit where it is due If you are on Rails 6.1 or later, you can build a class string conditionally today, no gems: ```erb <%= tag.div class: class_names("btn", "btn-primary", active: @active) do %> Click me <% end %> ``` `class_names` is a public alias for `token_list` in `ActionView::Helpers::TagHelper`. It takes strings, arrays, and hashes, splits on whitespace, drops falsy values, dedups the tokens, and hands back an HTML-safe string. For the everyday cases it is genuinely fine, and clsx agrees with it token for token: ```ruby require "clsx" require "action_view" # In an ERB template you call class_names(...) bare; here we mix it into an object. view = Object.new.extend(ActionView::Helpers::TagHelper) view.class_names("a", "b") # => "a b" Clsx["a", "b"] # => "a b" view.class_names(foo: true, bar: false) # => "foo" Clsx[foo: true, bar: false] # => "foo" view.class_names("a b", "b c") # => "a b c" (dedups across tokens) Clsx["a b", "b c"] # => "a b c" view.class_names("a", ["b", ["c"]]) # => "a b c" (flattens nesting) Clsx["a", ["b", ["c"]]] # => "a b c" ``` So if that is all you need, you need nothing. Use the built-in. I mean it. The rest of this post is about the four places that "all you need" runs out. ## Reason 1: it comes bundled with ActionView `class_names` is a method on `ActionView::Helpers::TagHelper`. It does not actually need a live view, no request, no output buffer. It needs the module. But the module is part of ActionView, so to join two strings in a Sinatra app or a plain service object, you load a whole view framework and mix it in by hand: ```ruby # In a plain object with nothing required, class_names is not defined: class_names("a", active: true) # => NoMethodError # You pull ActionView in and extend the module onto an object: require "action_view" view = Object.new.extend(ActionView::Helpers::TagHelper) view.class_names("a", active: true) # => "a" ``` That is the itch that started the split. I had put the class builder inside a Rails gem because Rails is where I was working that week. Then I wanted the same thing in a Phlex component, and in a plain presenter object, and reaching for ActionView to get it felt absurd. There is nothing Rails-specific about joining class names. So I pulled the logic into clsx-ruby, one file, about 130 lines, zero runtime dependencies, and left clsx-rails as a shim on top: ```ruby require "clsx" is_active, is_disabled = true, false Clsx["btn", "btn-primary", active: is_active, disabled: is_disabled] # => "btn btn-primary active" ``` ## Reason 2: empty results, and what happens on garbage `class_names` and clsx agree on the common cases. The one difference I lean on daily is what they return when nothing applies: ```ruby view.class_names(nil, false) # => "" (renders class="") Clsx[nil, false] # => nil (Rails tag helpers skip it) ``` Rails skips a `nil` class attribute, so `Clsx[...]` never renders an empty `class=""` on a component that had nothing to add. `class_names` gives you `""`, which renders. There is one honest point the other way. `class_names` returns an `html_safe` string; clsx returns a plain `String`. Inside a `class:` attribute that is a wash, Rails escapes the value either way and class tokens have nothing to escape. If you interpolate clsx output raw somewhere else, it is a normal string and gets escaped like one, which is the safe default, not a footgun. But if you specifically want `html_safe` output, `class_names` hands it to you and clsx does not. The rest is robustness. Neither of these inputs is something you write on purpose, but a helper somewhere eventually hands the builder something weird, and the two disagree on what to do with it: ```ruby # A complex value used as a hash key. view.class_names([{ foo: true }, "bar"] => true) # => "[{foo: true}, "bar"]" Clsx[[{ foo: true }, "bar"] => true] # => "foo bar" # An uncalled lambda and a stray boolean. view.class_names(proc {}, true) # => "#<Proc:0x...> true" (escaped into your markup) Clsx[proc {}, true] # => nil ``` `class_names` stringifies whatever it gets and escapes it into the attribute; clsx resolves a complex key recursively and ignores a bare `Proc` or `true`. When an `admin_link` helper accidentally hands you an uncalled lambda, clsx drops it and `class_names` prints a `Proc`'s address into your HTML. (There is also a cosmetic gap: `class_names(" a\tb ")` keeps a leading empty token, `" a b"`; clsx normalizes to `"a b"`. Browsers ignore the extra space, so this one is tidiness, not a bug.) ## The full vocabulary The name is a homage: clsx-ruby is modeled on [lukeed's `clsx`](https://github.com/lukeed/clsx), the tiny JavaScript package, so the argument model lines up with what React developers already know. Since the differences above are really about what counts as a class and what counts as truthy, here are the rules in one place. clsx takes strings, symbols, numbers, hashes, arrays, and any nesting of those: ```ruby Clsx["foo", true && "bar", "baz"] # => "foo bar baz" Clsx[:foo, :"bar-baz"] # => "foo bar-baz" Clsx[1, 2, 3] # => "1 2 3" Clsx[["foo", nil, false, "bar"]] # => "foo bar" Clsx["foo", ["bar", { baz: false }, ["hi", ["there"]]]] # => "foo bar hi there" ``` A hash includes each key whose value is truthy, in declaration order: ```ruby Clsx[foo: true, bar: false, baz: 2 > 1] # => "foo baz" ``` The one rule that trips up people coming from JavaScript: in Ruby only `false` and `nil` are falsy. So `0`, `""`, `[]`, and `{}` are all truthy and all keep their key. ```ruby Clsx["foo" => 0, bar: []] # => "foo bar" ``` And two conveniences the JS `clsx` does not have. Duplicates are removed even across multi-token strings, and an empty result is `nil`, not `""`: ```ruby Clsx["foo bar", "foo"] # => "foo bar" Clsx[" "] # => nil ``` Every line above is a real result. `bundle add clsx-ruby`, drop them into a REPL, and check. ## Reason 3: it is slower, and here is the honest version of that clsx is faster than `class_names` per call. I reproduced it against the real `ActionView` helper (not a stand-in), timing only the cases where both produce identical output, on Ruby 4.0.6 and an M1 Pro: | Scenario | clsx-ruby | Rails `class_names` | Speedup | |---|---|---|---| | Token | 5.1M i/s | 674K i/s | **7.5x** | | Long utility | 572K i/s | 116K i/s | **4.9x** | | Utility string | 1.2M i/s | 248K i/s | **4.9x** | | Multiple strings | 1.4M i/s | 334K i/s | **4.1x** | | String array | 1.2M i/s | 307K i/s | **4.0x** | | Hash | 1.5M i/s | 475K i/s | **3.2x** | | String + hash | 1.0M i/s | 365K i/s | **2.9x** | That table is one representative run; the geometric mean held around 4x across three. The interesting number is not the 7.5x on a lone token, which is the least realistic input anyone would reach for a builder to handle, it is the 2.9x on the busiest, most Tailwind-like input. The speedup shrinks as the work grows, so the low end is the honest one. A caveat on that gap. The gem's README quotes a more conservative 2 to 4x, because it benchmarks against a dependency-free replica of `class_names`. Part of the extra margin here is not a faster join, it is work clsx skips: `class_names` builds an `html_safe` buffer and un-escapes HTML on every call, and my identical-output filter compares string content, not that safety step. So the pure algorithm-to-algorithm number is the README's 2 to 4x; the wider figure is end-to-end against the real helper, which is what a Rails view actually pays. The gem ships its [benchmark](https://github.com/svyatov/clsx-ruby/blob/main/benchmark/vs_rails.rb); run it yourself. Now the honest part. This will almost never make a page faster. A class builder runs a handful of times per request, and your render time lives somewhere else entirely: allocations, HTML escaping, partial lookup, the N+1 you have not found yet. A 4x speedup on 0.1% of the work rounds to nothing. Where it actually shows up is call count. Render a table with 5,000 rows and three conditional-class calls each, and now the helper runs 15,000 times in one response. That is the case where "4x faster per call" stops being a micro-benchmark and starts being real milliseconds. If your views do not do that, treat the speed as a nice-to-have and pick clsx for the other three reasons. ## Reason 4: it cannot merge Tailwind classes This is the one neither `class_names` nor plain clsx can touch: ```ruby view.class_names("px-2", "px-4") # => "px-2 px-4" Clsx["px-2 px-4"] # => "px-2 px-4" ``` Both keep both classes, because neither knows that `px-2` and `px-4` are the same knob set twice. And in Tailwind, shipping both is a bug you cannot see. The winner is not the last class in the attribute, it is whichever rule Tailwind emitted later in the compiled stylesheet, and Tailwind orders by its own scale, not by what you wrote. That is deterministic, so it will not flip between machines, but it is also not your call: you ship a silently dead class, and which one dies is decided by Tailwind's internal ordering rather than your intent. If you have written React with Tailwind, you already know the fix, even if you have never looked at it. That `cn(...)` helper everyone copies out of shadcn/ui is literally `twMerge(clsx(inputs))`: clsx builds the string, `tailwind-merge` collapses the conflicts so the class you wrote last is the one that survives. clsx does the same, split into two functions so you only pay for merging when you ask for it. The merge is opt-in. clsx-ruby stays dependency-free; you add the [`tailwind_merge`](https://github.com/gjtorikian/tailwind_merge) gem and wire it up once: ```ruby # Gemfile gem "tailwind_merge" # config/initializers/clsx.rb require "clsx/tailwind_merge" Clsx.merger = TailwindMerge::Merger.new ``` That adds `twm` (and `Twm[]`, and `Clsx.twm`) alongside `clsx`. `clsx` and `cn` stay pure; only `twm` merges, and the last one you wrote wins, whichever order you wrote it in: ```ruby Twm["px-2 px-4"] # => "px-4" Twm["px-4 px-2"] # => "px-2" (written order, not Tailwind's) Twm["p-4", "p-2", "bg-red", "bg-blue"] # => "p-2 bg-blue" Clsx["px-2 px-4"] # => "px-2 px-4" (unchanged) ``` That second line is the whole point: your written order becomes authoritative, which is exactly what raw Tailwind does not honor. It is also group-aware, so it only collapses classes that genuinely conflict. `px-3` and `pr-4` set different things, so both survive, but `px-3` is the broader knob (it includes padding-right), so written last it wins: ```ruby Twm["px-3 pr-4"] # => "px-3 pr-4" (different groups, both kept) Twm["pr-4 px-3"] # => "px-3" (px-3 covers pr, and it came last) Twm["px-[13px] px-[14px]"] # => "px-[14px]" (arbitrary values too) ``` And because `twm` takes the same inputs as `clsx`, you get the conditional syntax and the merge in one call: ```ruby Twm[["px-2", "rounded"], "px-4", "px-6": active] # => "rounded px-6" (active) ``` You set `Clsx.merger` once at boot and read it per request. Merging is real work: `tailwind_merge` parses each class into its group, which is why it keeps a result cache and why it is worth doing only when asked. That is also why I kept `clsx` and `twm` separate. An early prototype had a global switch that routed every call through the merger (never shipped, so do not go looking for it), and I talked myself out of it: most calls have no conflict to resolve, so paying the merge cost on all of them to help a few is the wrong default. The merger slot is pluggable, it just has to respond to `merge`. The default is Garen Torikian's `tailwind_merge`, which I use enough that I have [two](https://github.com/gjtorikian/tailwind_merge/pull/79) [PRs](https://github.com/gjtorikian/tailwind_merge/pull/80) in it, one making that result cache thread-safe and one speeding up the hot path, both shipped in its 1.5.2. If you need more throughput, a Rust-backed alternative (`tail_merge`) exists, though confirm its Tailwind version support against your setup. ## Which call do I reach for? There are a few ways in, which looks like more than it is. They all run the same code. - `Clsx[...]` and `Cn[...]` (the bracket form) work anywhere, no setup. This is what I use in plain Ruby. - In Rails views (ERB, HAML, or Slim), clsx-rails gives you `clsx(...)` and `cn(...)` as bare helpers, no include. - In a ViewComponent, a Phlex component, or any object, `include Clsx::Helper` once and you get `clsx`/`cn` (and `twm` if you wired it up) as methods. - `Clsx.clsx(...)` / `Clsx.cn(...)` are the module-method form for when you do not want either. `cn` is just a shorter alias for `clsx`. Pick whichever reads better in the line. ## Using it outside Rails The whole point of the split is that none of this needs Rails. In a Phlex component you include the helper once and call it like any method: ```ruby require "phlex" require "clsx" class Badge < Phlex::HTML include Clsx::Helper def initialize(color: :blue, pill: false, class: nil) @color = color @pill = pill @html_class = binding.local_variable_get(:class) # `class` is a keyword end def view_template(&block) span(class: clsx("badge", "badge-#{@color}", @html_class, pill: @pill), &block) end end Badge.new(color: :red, pill: true, class: "badge ml-2").call { "New" } # => New ``` One line in there is pure Ruby trivia. You can name a keyword argument `class:`, but you cannot read it back as `class` (it is a reserved word, so `@html_class = class` is a syntax error). `binding.local_variable_get(:class)` is the escape hatch that fetches the local by name. The payoff is the cross-argument dedup: `badge` appears once even though the caller passed it and the component added it too. That is the thing you actually want when a component merges its classes with a caller's, and it is tedious to write by hand every time. The same include works in a ViewComponent base class, a Sinatra route, or a bare presenter. Phlex, for the record, has its own answer for the simple case: `class:` accepts an array and compacts falsy entries, and its `mix` helper merges attribute hashes. Reach for clsx when you want the hash-conditional syntax or the cross-argument dedup, and `twm` when you want Tailwind conflicts resolved, which none of Rails, ViewComponent, or Phlex do on their own. ## What changed since 2024, and do you have to migrate The old post covered clsx-rails around v1: the basic string, array, and hash syntax, Rails only. Since then: - v2 (2025) rewrote the algorithm for a 2 to 5x speedup and dropped Rails 6.1 and 7.0. - v3 (2026) extracted the engine into clsx-ruby and made clsx-rails a thin adapter over it. It raised the floor to Ruby 3.2+ and Rails 7.2+. - v3.1 added the `twm` Tailwind merge through clsx-ruby 1.2. If you are on an older clsx-rails, the upgrade is quiet. The breaking changes in v3 are the Ruby and Rails version floors, not the helpers. Same `clsx` and `cn`, same output. The one snag: `Clsx::VERSION` now reports the clsx-ruby core version, and the adapter's own version moved to `Clsx::Rails::VERSION`, so anything that read the old constant needs a one-line update. New since you last looked: everything runs outside Rails now, and `twm` exists. ## When to use something else clsx builds a class string. That is the whole job. If your problem is bigger, it is the wrong tool: - You just need conditional classes in a Rails view and none of the four reasons bite? Use `class_names`. It is already there. - You want a variant system, the `size: :lg, intent: :danger` to full-class-list mapping React people know as CVA? That is [`class_variants`](https://github.com/avo-hq/class_variants), a different and larger idea, and it can lean on a merger like `twm` for the final conflict pass. - You want another plain conditional-class helper to compare against? [`klassnames`](https://github.com/komposable/klassnames) is the closest same-purpose gem for Rails; it does the conditional join without the framework-agnostic core, the `nil` return, or the Tailwind merge. - You want the smallest possible dependency and only ever pass plain strings? You can hand-roll a `compact.join(" ")` and skip the gem. You lose dedup, the hash syntax, `nil` handling, and the merge, but if you never wanted those, that is a fair trade. For everything between "join two strings" and "design a variant DSL," which is most of what view code actually does, clsx is the size that fits. `class_names` builds class strings inside a view. clsx builds them anywhere, keeps the weird inputs from leaking, and knows what to do when two Tailwind utilities disagree. That is the whole difference, and now it is one `bundle add` away. --- ## Ruby shipped the fix for SleeperGem 45 days before it happened - URL: https://svyatov.com/blog/ruby-shipped-the-fix-for-sleepergem-45-days-before-it-happened/ - Date: 2026-07-21 - Tags: ruby, security, opensource, devops On June 3rd, Bundler 4.0.13 shipped [a feature called cooldown](https://blog.rubygems.org/2026/06/03/cooldown-let-new-gems-be-vetted.html). The release post described the problem it solves like this: "an account is compromised, a malicious version ships, and any `bundle install` in the minutes that follow resolves straight to it." Forty-five days later, someone did exactly that to three gems. [Aikido Security disclosed the campaign](https://www.aikido.dev/blog/sleepergem-rubygems-supply-chain-attack) on July 19th and named it SleeperGem: malicious versions of `git_credential_manager`, `Dendreo`, and `fastlane-plugin-run_tests_firebase_testlab`. Two of those gems had sat untouched since 2019 and 2020, which is where the name comes from. (The third impersonates Microsoft's Git Credential Manager, and no report says whether that account was hijacked or simply the attacker's.) The clever part is what the payload does when it lands. Aikido found a `skip_install?` check that "scans for roughly 30 environment variables belonging to CI platforms, GitHub Actions, GitLab CI, CircleCI, Travis, Jenkins, Vercel, and does nothing if it spots one." It sits still in your pipeline and wakes up on your laptop. [StepSecurity reversed the native binary](https://www.stepsecurity.io/blog/sleepergem-compromised-rubygems-drop-persistent-backdoor) it drops: a daemon in `~/.local/share/gcm/`, a systemd user unit, a cron entry, and if you installed as root, a setuid shell at `/usr/local/sbin/ping6`. Most of the coverage stopped at "supply chain attack, be careful out there," then repeated numbers that do not survive a look at the registry. ## The numbers being repeated are not the numbers [The most-syndicated writeup](https://thehackernews.com/2026/07/sleepergem-uses-three-malicious.html) lists `Dendreo` versions 1.1.3 and 1.1.4 as "Published on October 14, 2017." The registry says 2017-10-14 is version **1.0.1**'s date, and that 1.1.2 shipped in October 2020. A 1.1.3 published three years before 1.1.2 is not a date, it is a copy-paste of the gem's first release. Same error on the fastlane plugin, where "February 06, 2018" belongs to 0.1.0. Both malicious releases went up in July 2026. That is the article the aggregators spent the next day copying. The scale number has the same shape. Aikido's "574,661 total downloads" is honest in context (it says all versions), but downstream it sits next to the attack and reads like blast radius. Here is where they live: | `fastlane-plugin-run_tests_firebase_testlab` | published | downloads | relative downloads | |---|---|---|---| | 0.3.1 | 2019-03-04 | **531,859** | `################################` | | 0.2.0 | 2018-07-17 | 16,509 | `#` | | 0.1.0 | 2018-02-06 | 10,619 | `#` | | 0.2.2 | 2018-11-29 | 6,323 | | | 0.3.0 | 2019-01-11 | 4,965 | | | 0.2.1 | 2018-09-27 | 4,892 | | | **0.3.2** | **2026-07-19** | yanked, count deleted | | One benign release from 2019 is 92.5% of it. `Dendreo` has 14,435 downloads across its entire seven-year life. Nobody publishes install counts for the malicious versions, and they can't: yanking a version removes it from the API. ## The mitigation was already on the shelf Cooldown makes Bundler refuse to resolve to a release younger than N days. The first malicious version went up on July 18th, and all of them were gone from the registry by the 21st. Nobody published the actual yank time, so three days is an upper bound, not a measurement, but a cooldown of seven would have skipped every one of them for as long as they existed. It is one line: ```ruby source "https://rubygems.org", cooldown: 7 ``` I checked it against a recent release. `concurrent-ruby` 1.3.8 went up on July 19th, the same day SleeperGem's last gem did: | Gemfile | resolves to | |---|---| | `source "https://rubygems.org"` | concurrent-ruby **1.3.8** (2 days old) | | `source "https://rubygems.org", cooldown: 7` | concurrent-ruby **1.3.7** | It also fails closed. If nothing in the registry is old enough to satisfy your cooldown, Bundler does not quietly install the newest version anyway. I forced that case with an absurd window, `cooldown: 36500`, about a hundred years, against `concurrent-ruby`: it refused and told me what it held back, `79 versions excluded by the cooldown setting; pass --cooldown 0 to bypass`. A guard that gives up silently when it cannot be satisfied is worse than no guard, because you think you have one. Cooldown is unset by default, so if you never added that line, June changed nothing for you. None of the SleeperGem coverage I can find mentions that the feature exists. ## What it doesn't buy you Cooldown is a delay, not a defense. It works here because this attacker was loud and got caught in days. Against a version that ages quietly for three weeks, seven days of patience buys nothing. It also does nothing about the actual hole. Neither Aikido nor StepSecurity says how the accounts were taken over. No vector, no phishing story, no statement about MFA in either direction. So every "this is why we need mandatory 2FA" reply is guessing, and mandatory MFA on RubyGems kicks in at 180 million downloads anyway. These gems are at 0.32% and 0.008% of that. It was never going to apply. RubyGems built the right thing early and left it switched off. Go switch it on. --- ## Learn Big O by measuring it, in Ruby - URL: https://svyatov.com/blog/learn-big-o-by-measuring-it-in-ruby/ - Date: 2026-07-20 - Tags: ruby, performance, algorithms, testing A very common way Ruby code gets slow at scale hides in a line that looks harmless: ```ruby records.select { |r| seen.include?(r.id) } ``` If `seen` is an Array, that is O(n²). Every one of the `n` records triggers an `include?` that scans up to `n` elements. It runs fine on the hundred rows you tested and falls over on the hundred thousand you didn't. You can see this coming, and you don't have to squint at the code to do it. You can measure the growth rate directly and watch it bend upward. That is what this post is about. Not the theory of Big O from a chart of curves, but Big O as something you can put on a clock. We are going to take real Ruby, run it on inputs that keep doubling, time each run, and let the complexity class fall out of the numbers, one at a time. By the end you will have measured O(1), O(log n), O(n), O(n log n), O(n²), and O(2ⁿ) with your own hands. And you will know exactly when the measurement is lying to you, because that turns out to be the harder and more useful half. I went looking for a `BigO.measure { some_code }` method, half expecting to build it. It already exists, it has been sitting on RubyGems since 2020, and the interesting part is how confidently it can be wrong. ## The whole idea: double the input, watch the clock Big O describes how the work grows as the input grows. Not how long something takes, but how the time *scales*. O(n) means double the input and the work roughly doubles. O(n²) means double the input and the work goes up about fourfold. O(1) means the input size doesn't matter at all. That "double the input" is the whole measurement technique, and it is older than any gem. It is called the doubling hypothesis, and it is exactly what Princeton teaches in its algorithms course. Run your code at some size `n`, then at `2n`, and look at the ratio of the two times: | Time ratio when you double n | Growth class | |---|---| | stays flat (~1×) | O(1) | | creeps up by a constant | O(log n) | | ~2× | O(n) | | a bit more than 2× | O(n log n) | | ~4× | O(n²) | | squares each step | O(2ⁿ) | If you do this across a wide range of sizes and fit the points to the curve `time = a · n^b`, the exponent `b` is the growth rate. Fit a straight line through the same points on log-log axes and its slope is that same `b`. That is the entire trick: measure at many sizes, fit a power curve, read the exponent. A linear algorithm gives `b ≈ 1`. A quadratic one gives `b ≈ 2`. Everything else lands somewhere you can read off a ruler. There is a gem that does the fitting for you. Before we let it, let's do it by hand once, so nothing about the result is magic. ## Every class, measured The tool is [`benchmark-trend`](https://github.com/piotrmurach/benchmark-trend) by Piotr Murach. Add it to a Gemfile with `gem "benchmark-trend"` and `bundle install`. It gives you two pieces: `Benchmark::Trend.range` to build a geometric ladder of sizes (with `ratio: 4`, each size is four times the last: 1000, 4000, 16000, and so on up to the max), and `Benchmark::Trend.infer_trend` to run your code at each size and fit the curves. One thing matters before we start, and it is the mistake everyone makes first. `infer_trend` times the *entire block* you give it. If you build your test data inside that block, you are timing the setup too, and the setup usually has its own complexity that swamps what you meant to measure. So build the input for each size first, then time only the operation. Here is a small helper that does exactly that: ```ruby require "benchmark/trend" # sizes: the geometric range of input sizes # prepare: builds the input for a given size, once, before timing # work: the operation whose growth we're measuring def measure(sizes, prepare:, &work) inputs = sizes.map { |n| prepare.call(n) } trend, fits = Benchmark::Trend.infer_trend(sizes, repeat: 4) do |n, i| work.call(inputs[i], n) end r2 = fits[trend][:residual] # how well the winning curve fit (R², 0 to 1) if trend == :exponential # A compounding curve has no polynomial exponent to read, so skip it. puts "best fit: #{trend} (compounding growth) R2=#{format('%.4f', r2)}" else b = fits[:power][:slope] # the power-law exponent: our growth "ruler" puts "best fit: #{trend} exponent b=#{format('%.2f', b)} R2=#{format('%.4f', r2)}" end end ``` Two blocks are in play here, and it helps to keep them straight. The one `infer_trend` calls receives `(n, i)`, the size and its index, and uses `i` to pick the matching pre-built input. The block *you* write and pass to `measure` receives that prepared input as its first argument and the size `n` as its second, so you will see signatures like `|array, n|` below (and `_n` when a demo doesn't need the size). Either way, `work.call(...)` is the timed part, never the setup. Save this helper as `measure.rb`; every demo below opens with `require_relative "measure"`, and each is a complete, runnable file once `benchmark-trend` is installed. (`repeat: 4` runs each size four times and averages, to smooth out noise.) Read two numbers out of every run. The `best fit` is the curve family the gem picked. The exponent `b` is the growth ruler: near 0 is flat, near 1 is linear, near 2 is quadratic. For an exponential curve there is no meaningful polynomial exponent, so the helper skips it and the family name carries the result. ### O(1): the lookup that doesn't care how big the haystack is Start with the class that feels like magic the first time you see it. A Hash lookup takes about the same time whether the Hash holds a thousand keys or a million: ```ruby require_relative "measure" LOOKUPS = 200_000 sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4) measure( sizes, # Build a Hash of n keys, plus a fixed batch of keys to look up. prepare: ->(n) { hash = (1..n).to_h { |k| [k, true] } keys = Array.new(LOOKUPS) { rand(1..n) } [hash, keys] } ) do |(hash, keys), _n| keys.each { |k| hash[k] } # always LOOKUPS lookups, no matter how big the Hash end ``` The batch is a fixed 200,000 lookups at every size. The Hash grows from a thousand keys to a million; the amount of work does not. Run it: ```text best fit: linear exponent b=0.26 R2=0.9976 ``` The exponent is 0.26, way below linear's 1. Flat-ish. It is not exactly 0, and the leftover is the machine, not the algorithm: most likely the Hash spilling out of CPU cache as it grows, so each lookup gets a little slower, though a single run can't cleanly separate that from noise or GC. This is also the shakiest measurement in the post, and worth knowing that up front. Rerun it and the exponent bounces around 0.2 to 0.3, and on a busy machine the fitter can even misname the family as `exponential`, because a flat line has no real trend for it to lock onto, so noise wins. That instability is itself the fingerprint of constant time. Hold the thought, because it is our first hint that the clock measures more than complexity. We will come back to it. ### O(log n): binary search halves the problem each step Logarithmic growth is the one people struggle to picture. It means each step throws away half of what is left, so doubling the input adds just one more step. Binary search on a sorted Array is the textbook case, and Ruby has it built in as `Array#bsearch`: ```ruby require_relative "measure" SEARCHES = 200_000 sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4) measure( sizes, prepare: ->(n) { array = (1..n).to_a targets = Array.new(SEARCHES) { rand(1..n) } [array, targets] } ) do |(array, targets), _n| targets.each { |t| array.bsearch { |x| x >= t } } # ~log2(n) comparisons each end ``` ```text best fit: power exponent b=0.12 R2=0.9906 ``` An exponent of 0.12: nearly flat, and notice it came in *below* the O(1) run's 0.26, not above. That is not a mistake, it is the lesson arriving early. Logarithmic growth is so slow that on a ruler measuring polynomial degree it sits right down on the floor with constant time, and here noise in the O(1) run even pushed it higher than the log one. Going from a thousand to a million elements, a 1000× jump, only about tripled the depth of each search. The takeaway to bank: O(1) and O(log n) both read as "small exponent, nearly flat," and timings alone cannot reliably tell them apart or even order them. We will make that a rule later. ### O(n): the linear scan from the opening Now the line that started this post. `Array#include?` walks the array element by element until it finds a match. Search for something that isn't there and it has to touch all `n` elements: ```ruby require_relative "measure" sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4) measure( sizes, prepare: ->(n) { (1..n).to_a } ) do |array, n| array.include?(n + 1) # absent value, so the scan can't stop early end ``` ```text best fit: linear exponent b=0.96 R2=1.0000 ``` Exponent 0.96, an R² of 1.0, and this time the gem named the family `linear` outright. Double the array and the scan takes twice as long. This is the shape hiding inside that `select` from the opening, and in a moment we will see what happens when you nest it. ### O(n log n): sort, and a first look at trouble Sorting is the workhorse of the "slightly worse than linear" class. Ruby's `Array#sort` is a quicksort variant, average O(n log n): ```ruby require_relative "measure" sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4) measure( sizes, prepare: ->(n) { (1..n).to_a.shuffle } # fresh shuffle so each sort starts unsorted ) do |array, _n| array.sort end ``` ```text best fit: power exponent b=1.09 R2=0.9998 ``` Look closely, because this is the crux of the whole post. The exponent is 1.09. Not 2. Barely above the linear scan's 0.96. Sorting is genuinely O(n log n), meaningfully more work than a linear pass, and the measurement can barely tell the difference. The log factor is nearly invisible to a power fit. That is not a flaw in this gem; it is a limit of the technique itself, and it has a whole section coming. For now, just notice that O(n) and O(n log n) landed almost on top of each other: 0.96 and 1.09. ### O(n²): the accidental one Here is the opening bug, built on purpose. Filter `n` rows, and for each row do an `include?` scan over an `n`-element Array. That is `n` rows times an `n`-element scan: ```ruby require_relative "measure" sizes = Benchmark::Trend.range(500, 8_000, ratio: 2) # smaller: n² gets big fast measure( sizes, prepare: ->(n) { rows = (1..n).to_a seen = (n + 1..2 * n).to_a # values that are absent, forcing a full scan [rows, seen] } ) do |(rows, seen), _n| rows.select { |r| seen.include?(r) } end ``` ```text best fit: power exponent b=1.99 R2=1.0000 ``` Exponent 1.99, near enough to 2. That is quadratic, plain as day, and it is the number that separates a page that loads instantly from one that times out. Swap that Array for a Set and the exponent drops back toward 1, because a Set is Hash-backed and its `include?` is average O(1). That is why a Set is the right structure for a membership check, and we will gate exactly this difference in CI later. ### O(2ⁿ): the one that ends the party Exponential growth is the cliff. Each `+1` to the input roughly doubles the work. The classic offender is naive recursive Fibonacci, where every call spawns two more: ```ruby require_relative "measure" def fib(n) = n < 2 ? n : fib(n - 1) + fib(n - 2) # Exponential workloads need small, closely-spaced sizes, not a wide sweep. # infer_trend accepts any array of sizes, not just Trend.range output. sizes = (20..32).step(2).to_a measure(sizes, prepare: ->(n) { n }) do |n, _i| fib(n) end ``` ```text best fit: exponential (compounding growth) R2=0.9999 ``` The gem names it `exponential` and I skip the power exponent here, because for a compounding curve the polynomial ruler is meaningless. This is why `fib(50)` would outlast your patience while `fib(30)` returns instantly. The sizes only go to 32 for a reason. Here is the whole ladder from one run, so you can see the ruler climb: ```text O(1) Hash#[] best fit: linear exponent b=0.26 R2=0.9976 O(log n) bsearch best fit: power exponent b=0.12 R2=0.9906 O(n) include? best fit: linear exponent b=0.96 R2=1.0000 O(n log n) sort best fit: power exponent b=1.09 R2=0.9998 O(n^2) select+incl best fit: power exponent b=1.99 R2=1.0000 O(2^n) fib best fit: exponential (compounding growth) R2=0.9999 ``` Your exact numbers will differ, because this is a stopwatch on a real machine. Even the order at the flat end can wobble, as O(1) and O(log n) just did. What holds is the climb once there is real growth to see: near-flat, then a linear ramp near 1, then a quadratic wall near 2, then off the exponential cliff. Here is the same story as curves:  ## The one-call version, and its rough edges You do not need the helper. The core of `benchmark-trend` is a single call, and it is worth seeing raw: ```ruby require "benchmark/trend" sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4) arrays = sizes.map { |n| (1..n).to_a } trend, fits = Benchmark::Trend.infer_trend(sizes, repeat: 4) do |_n, i| arrays[i].include?(-1) # absent value, so the scan is O(n) end puts "best fit: #{trend}" puts "residual (R2): #{fits[trend.to_sym][:residual].round(4)}" ``` ```text best fit: linear residual (R2): 0.9999 ``` `infer_trend` returns the winning family as a Symbol and a Hash of every fit it tried. That is genuinely close to the `BigO.measure { }` I went looking for. But it has three edges worth knowing before you trust its output, and none of them are in the README's happy path. **It fits four curve families, and quadratic isn't one of them.** The candidates are exponential, power, linear, and logarithmic. There is no dedicated `n²` model and no `n log n` model. This is why we read polynomial degree off the *power* fit's exponent instead of expecting a name like "quadratic." An exponent near 2 is how quadratic shows up. If you were hoping the tool would just print "O(n²)," it can't, and now you know why. **The residual is R², and higher is better.** In the output above, `residual: 0.9999` means the linear curve explained almost all the variance in the timings. Values run from 0 (useless) to 1 (perfect). Treat anything under about 0.9 as "the fit didn't take, don't trust the label." Strictly, the gem picks the winner on R² *and* a small penalty for model complexity, so a fancier curve has to earn its win rather than edge ahead on a rounding error, but R² is the number you read. **The human-readable trend string has a bug.** Every fit carries a pretty-printed formula, and for a power fit it prints its two numbers in the wrong slots. Here is a full run against `sort`, which fits a power law, printing the formula next to the real values pulled from the Hash: ```ruby require "benchmark/trend" sizes = Benchmark::Trend.range(1_000, 1_000_000, ratio: 4) arrays = sizes.map { |n| (1..n).to_a.shuffle } _trend, fits = Benchmark::Trend.infer_trend(sizes, repeat: 4) do |_n, i| arrays[i].sort end power = fits[:power] puts "printed string: #{power[:trend]}" # what the gem shows you puts "slope (exponent): #{power[:slope].round(3)}" # the REAL growth exponent puts "intercept (coef): #{power[:intercept]}" # the REAL coefficient ``` ```text printed string: 1.09 * x^0.00 slope (exponent): 1.086 intercept (coef): 3.55684051103109e-08 ``` The string reads `1.09 * x^0.00`, which looks like an exponent of zero, a flat line. But the real exponent is 1.086, sitting in the `slope` field, and the tiny coefficient is in `intercept`. The formatter swapped them. The gem's own README shows the same swapped shape in its example output, so this is not a fluke on my machine. The lesson is simple: read `:slope` and `:intercept` from the Hash, and ignore the pretty string. Those edges aside, the fitted curve buys you something useful: it can project a runtime at a size you never ran. `Benchmark::Trend.fit_at` takes the slope and intercept from a fit and evaluates the curve at any `n`. Feed it the O(n²) filter's power fit and ask what a hundred thousand rows would cost: ```ruby power = fits[:power] # from the O(n²) measurement above at = Benchmark::Trend.fit_at(:power, slope: power[:slope], intercept: power[:intercept], n: 100_000) puts "projected time at n=100_000: #{at.round(2)} s" # => projected time at n=100_000: 31.3 s ``` The absolute seconds are machine-specific and will swing between runs, so trust the order of magnitude, not the decimal. That is the whole reason complexity is worth knowing: an exponent near 2 means roughly ten times the rows costs a hundred times the time, and now you can see the wall before you hit it in production. One more thing to know up front, not a bug but a fact. `benchmark-trend` last shipped version 0.4.0 in March 2020, and its RSpec companion `rspec-benchmark` shipped 0.6.0 two days later. Neither has had a release since. They still install and run cleanly on Ruby 4.0, which is what every example here runs on, but you are adopting stable, dormant code, and that is worth a conscious choice. ## Where the stopwatch lies Everything so far makes measurement look easy. It isn't, and the gap between "I measured it" and "I know its complexity" is where people get burned. Four ways the clock misleads you. **It measures Big Theta, not Big O.** This is the subtle one. Big O is a worst-case upper bound, a promise about the worst input the algorithm could ever face. A stopwatch can't measure a promise. It measures what actually happened on the inputs *you* chose. Feed quicksort already-sorted data and you might see one shape; feed it its pathological worst case and you'll see another. What you get back is the observed order of growth on your workload, which theorists call Big Theta, not the worst-case Big O. The Python equivalent of this technique, the [`big_O`](https://github.com/pberkes/big_O) package, says so flatly in its own docs: "Strictly speaking, we're empirically computing the Big Theta class." Every demo above quietly chose its inputs. The `include?` scan searched for an *absent* value on purpose, to force the full-length worst case. Change that decision and you change the number. **It is blind to log factors.** Remember sort landing at 1.09, right next to the linear scan's 0.96? That is not bad luck, it is arithmetic. When you double the input, an O(n) algorithm's time doubles and an O(n log n) algorithm's time slightly-more-than-doubles, and "slightly more" is nearly invisible against measurement noise. Princeton's own course notes put it bluntly: you "cannot identify logarithmic factors with the doubling hypothesis." So a power fit cannot cleanly separate O(n) from O(n log n). If your exponent lands around 1, you have learned it is roughly linear, and to tell linear from linearithmic you have to go read the code. The clock won't do it for you. **A too-narrow range invents an answer.** Watch the same linear scan, measured over a tiny range of sizes and then a wide one: ```ruby op = ->(array, n) { array.include?(n + 1) } # same O(n) scan both times build = ->(n) { (1..n).to_a } puts "narrow range (100..800):" measure(Benchmark::Trend.range(100, 800, ratio: 2), prepare: build, &op) puts "wide range (1_000..1_000_000):" measure(Benchmark::Trend.range(1_000, 1_000_000, ratio: 4), prepare: build, &op) ``` ```text narrow range (100..800): best fit: constant exponent b=0.60 R2=1.0000 wide range (1_000..1_000_000): best fit: linear exponent b=0.96 R2=1.0000 ``` Over 100 to 800 elements, a linear scan looks *constant*, with a perfect R² of 1.0 on the wrong answer. (`constant` here is not a fifth family; it is what the gem calls a linear fit whose slope came out flat at zero, and `perform_constant` later is that same zero-slope special case.) At those sizes the scan is so fast that fixed overhead drowns the actual growth. The high R² gives you false confidence in a false label. Only across a wide range, where the real work dominates, does the linear shape appear. The rule the research literature agrees on: your smallest size must be big enough that the operation itself, not the overhead around it, dominates the clock. **The machine leaks into the measurement.** Garbage collection pauses, CPU cache behavior, other processes, JIT warmup: all of it lands in the timings. The usual teaching model says these effects only shift the constant factor and leave the exponent alone. Mostly true, but not a guarantee. Our own O(1) Hash lookup came back at exponent 0.26 instead of 0, most likely because its memory working set grew past the CPU cache. In a garbage-collected runtime, effects that scale with `n` can bend the exponent itself. `benchmark-trend` fights back where it can: it uses a monotonic clock, runs `GC.start` before each size, and averages repeated runs when you pass `repeat:`. It does not warm up the code, though, and wall-clock timing in Ruby is noisier than the deterministic operation-counting the academic papers use. Measure the same thing twice and you will get two slightly different exponents. That is normal. None of this makes the technique useless. It makes it a tool with a manual. You measure to build intuition and to catch regressions, and when two adjacent classes are ambiguous, you fall back to reading the code. ## Gating complexity in CI Measuring by hand teaches you the shapes. The payoff at work is different: catch the day someone turns your O(n) into an O(n²) without noticing. That is what [`rspec-benchmark`](https://github.com/piotrmurach/rspec-benchmark) is for. It wraps `benchmark-trend` in RSpec matchers, so you assert a growth class the way you assert anything else. The matchers are `perform_constant`, `perform_logarithmic`, `perform_linear`, `perform_power`, and `perform_exponential`. There is no `perform_quadratic`, for the four-families reason from earlier; a quadratic is a `perform_power` whose exponent lands near 2. Here is a gate on the membership filter from the opening, pinned to a Set so it stays linear: ```ruby require "benchmark/trend" require "rspec-benchmark" require "set" RSpec.configure { |c| c.include RSpec::Benchmark::Matchers } SIZES = Benchmark::Trend.range(200, 3_200, ratio: 2) ROWS = SIZES.to_h { |n| [n, (1..n).to_a] } SEEN_SET = SIZES.to_h { |n| [n, (n + 1..2 * n).to_a.to_set] } RSpec.describe "membership filtering" do it "stays linear with a Set" do expect { |n, _i| ROWS[n].select { |r| SEEN_SET[n].include?(r) } } .to perform_linear.in_range(200, 3_200).ratio(2).sample(100).times end end ``` Two details carry the weight. The block takes `n`, so the work has to scale with `n`: we key the pre-built inputs by size and look them up, exactly like the helper did, so we never time the setup. And `in_range(min, max).ratio(r)` rebuilds the same geometric ladder `Benchmark::Trend.range` would, which is why keying the data by `n` lines up. With `SEEN_SET` a Set, `include?` is average O(1), so filtering `n` rows costs O(n) total and the gate passes green. Now regress it. Swap that Set back to a plain Array and keep the linear gate: ```ruby SEEN = SIZES.to_h { |n| [n, (n + 1..2 * n).to_a] } # Array, not Set it "is supposed to stay linear (but doesn't)" do expect { |n, _i| ROWS[n].select { |r| SEEN[n].include?(r) } } .to perform_linear.in_range(200, 3_200).ratio(2).sample(100).times end ``` The same filter is now O(n²), the gate goes red, and it names the class it actually found: ```text Failures: 1) membership filtering is supposed to stay linear (but doesn't) Failure/Error: expect { |n, _i| ROWS[n].select { |r| SEEN[n].include?(r) } } expected block to perform linear, but performed power ``` That "expected linear, but performed power" is the regression caught before production. One honest warning, straight from the gem's own README: these matchers are "potentially flaky." They are timing-based, so a loaded CI machine can occasionally flip a borderline result. Keep them out of your normal suite. Tag them, give them their own run, and lean on them for the classes that are unambiguous, an O(n) that must not become O(n²). ## When to reach for it, and when not Empirical measurement is a teacher and a smoke alarm, not a proof. Reach for it to build a feel for a method you don't know: put `Array#include?`, `Set#include?`, and `Hash#[]` on the clock and the difference stops being abstract. Ruby's docs rarely state the complexity of built-in methods (`bsearch` is a rare one that spells out O(log n); `include?` and `sort` say nothing), so measuring is often how you find out. And reach for it to guard a hot path in CI, where a `perform_linear` gate on the endpoint that melted last quarter is cheap insurance. Keep in mind what it does *not* measure: the constant factor. `benchmark-trend` tells you the shape of the curve, not which of two methods is faster at the size you actually run. That second question, "is a Set worth it for my 50 items," belongs to `benchmark-ips` or the stdlib `Benchmark`. The two are complementary, one for the growth, one for the wall-clock at a fixed size. Then the boundaries. Don't reach for it to prove a worst-case bound; it measures the case you fed it. Don't trust it to split two adjacent classes; when the exponent sits near 1, the clock has told you everything it can, and the code has the rest. Don't point it at IO, either. Every demo here is pure in-memory CPU work, which is where wall-clock inference behaves. A loop of database queries or network calls has its growth swamped by connection and IO variance, so the exponent turns to mush. For the classic N+1 query, count the queries, don't time the exponent. And remember a worse Big O can still win at the sizes you actually run. For small `n`, constants and memory layout dominate, which is why hybrid sort implementations fall back to insertion sort on small chunks even though it is O(n²). Big O is the shape of the curve as `n` grows, not the winner at any single size. When it matters, measure the crossover for your own case. So measure your code. Watch the exponent climb from a flat line to a linear ramp to a quadratic wall. Just keep one hand on the manual, because the clock will tell you a clean story, and sometimes the story is wrong. --- ## Keeping code alive on a DOM you don't own: 12-year Chrome extension story - URL: https://svyatov.com/blog/keeping-code-alive-on-a-dom-you-dont-own-12-year-chrome-extension-story/ - Date: 2026-07-17 - Tags: webdev, showdev, javascript, sideprojects In April 2014 I wanted to sort posts on the Hacker News front page by points, by time, or by comments. Nothing I found did it without cluttering the page, so I wrote a tiny Chrome extension over a couple of days, uploaded it to the Web Store, and mostly stopped thinking about it for ten years. I touched it exactly once in that decade, in 2019, to fix the selectors. Then in March 2024 I rewrote it from scratch, with the old version still working fine: I wanted TypeScript, React, and tests, and Manifest v3 while I was in there. That's when I started actually maintaining it. It's called [Hacker News Sorted](https://chromewebstore.google.com/detail/hacker-news-sorted/djkcnbncofmjekhlhemlkinfpkamlkaj), it's now at v2.6.1, and it has one dependency that never appears in package.json: the exact HTML structure of the Hacker News front page. HN can change that structure any day, without a changelog, and they owe me nothing. Sorting 30 rows of a table is a weekend project. This post is about everything else: the selector that survived a layout change and the one that didn't, the badge that tells users it's my fault, the GitHub Action that checks HN's HTML every morning, and the timestamps HN quietly rewrites. The obvious question first: HN has an official API, so why scrape the DOM at all? Because the extension doesn't need data, it needs to rearrange the page you're already looking at. Every number it sorts by is already sitting in the rows, true timestamps included. Fetching the same 30 items over the network would only add latency, a wider permission surface, and a privacy story to explain. ## The selector war HN's front page is one big `