Contributing

Adding a rule to an existing gate is usually a single TOML edit. Adding a new gate also needs a small Rust file. The build pipeline picks up TOML changes automatically; the generator in build.rs emits the Rust gate function from the TOML on every build.

Simplest case: add shellcheck to devtools.toml as always-safe.

# rules/devtools.toml
[[programs]]
name           = "shellcheck"
unknown_action = "allow"  # always safe (read-only)

Then cargo build --release. Done. Flag-conditional behavior:

# rules/devtools.toml
[[programs]]
name           = "prettier"
unknown_action = "allow"
[[programs.ask]]
reason        = "Writing formatted files"
if_flags_any  = ["--write", "-w"]

# rules/devtools.toml
[[custom_handlers]]
program     = "ruff"
handler     = "check_ruff"
description = "ruff format asks unless --check or --diff present"

Then implement check_ruff in the gate file. The generated gate returns Skip for this program, letting the custom handler take over.

Custom handlers return one of the same four gate results used by the generated functions:

GateResult::skip()               // this gate has no opinion
GateResult::allow()              // explicitly safe
GateResult::ask("Description")  // mutation or unresolved risk
GateResult::block("Explanation") // deterministic safety floor

1. Create rules/newgate.toml. Pick a priority that slots in correctly; lower runs first, basics at 100 is always last.

[meta]
name        = "newgate"
description = "New category of tools"
priority    = 50
[[programs]]
name           = "newtool"
unknown_action = "ask"
[[programs.allow]]
subcommand = "list"
[[programs.ask]]
subcommand = "create"
reason     = "Creating resource"

2. Create src/gates/newgate.rs. Thin wrapper around the generated function.

use crate::generated::rules::check_newgate_gate;
use crate::models::{CommandInfo, GateResult};
pub fn check_newgate(cmd: &CommandInfo) -> GateResult {
    check_newgate_gate(cmd)
}

3. Register in src/gates/mod.rs. Add to the GATES array in priority order.

mod newgate;
pub use newgate::check_newgate;
pub static GATES: &[(&str, GateCheckFn)] = &[
    // … other gates …
    ("newgate", check_newgate),
    ("basics", check_basics), // basics last
];

1. Build via mise. The project uses a mise task to build the WebAssembly module. It compiles the Rust codebase and uses Zig CC via a wrapper script to compile the C-based tree-sitter parser without requiring a manual clang/WASI-sdk installation. Run the following command:

$ mise run build-wasm

This compiles the target, runs wasm-bindgen to generate bindings in docs/src/wasm/, and runs wasm-opt with the bulk memory feature enabled to optimize the output size.

Read the Reason style guide before writing new reason strings. The 250-char limit, no-em-dashes rule, and authorization-hedge ban are enforced by build.rs and by code review.