# RULES

## Automation law

- Use Mise as the only public automation interface.
- Treat `mise.toml` files as the source of truth for tools, tasks, dependencies, and orchestration.
- Use an existing Mise task instead of its npm script, Node script, formatter, test runner, or browser runner.
- Keep root npm scripts as task implementation details, and add no extension package scripts.
- Add missing automation to the appropriate `mise.toml`.
- Stop when Mise cannot run tasks or its project configuration is invalid; fix ordinary task failures and retry.

## Task selection

- Run `mise tasks --all` to list tasks; address them as `//:<task>` and `//extensions/<name>:<task>`.
- Choose the smallest task that proves each change; continue through remaining requested work once it passes.
- During iteration, use the affected extension's `lint`, `test`, or `check`.
- For complete verification, run root `//:test` or `//:check` once instead of expanding per-extension wrappers.
- Run `//:ci`, `//:e2e`, or unrelated suites only when the human requests that exact wider gate.
- Do not treat commits, merges, or generic verification requests as wider-gate requests.
- Validate Mise configuration after changing it: `mise tasks validate`, or `mise -C extensions/<name> tasks validate`.
- Load the `pi-ext-automation` skill before authoring tasks, editing `mise.toml`, reinstalling hooks, or diagnosing Mise failures.

## Repository safety

- Preserve unrelated dirty work, and do not delete noisy research, cache, or untracked files unless asked.
- Never print secrets, and never run privileged commands.

## Extension diagnostics

- Every extension exposes the independently installable debug interface specified in `extensions/DEBUG.md`.
- Keep the generated logger inside its owning extension; never import the generator or another extension at runtime.
- Change debug plumbing through the declarative codegen template and `//:codegen`, not by editing generated files.
- Keep debug off by default and diagnostic failures nonfatal; do not write diagnostics into Pi's TUI or machine-readable stdout.
- Debug files under OS user locations require explicit approval before this agent creates, modifies, or deletes them.

## Extension settings

- Declare extension configuration through the generated extension-local helper specified in `extensions/SETTINGS.md`.
- Change settings plumbing through the codegen template and `//:codegen`, not by editing generated files.
- Resolve each value as flag, env, trusted project, user, default; never read untrusted project settings.
- Report invalid values instead of falling back to a lower source.
- Keep credentials in env or Pi's credential store, never in settings.
- Changing the user's `~/.pi/agent/settings.json` requires explicit approval of the exact edit.

## CI

- Keep repository CI definitions under `.ci/*.kdl` and delegate execution to `CI=true mise run //:ci`.
- Full CI runs on Luci after pushing; run it locally only when explicitly requested.

## Git hooks

- Keep pre-commit and pre-push limited to `check` and `lint`.
- Manage hooks through `mise generate git-pre-commit`.

## Model evaluation

- Judge models by projected API cost from catalog prices, even when access is subscription-billed.
- Subscriptions change what is paid, not how models are judged.

## Markdown

- Write one sentence per line.
- Preserve semantic line breaks.
- Let rumdl handle Markdown structure instead of manually reflowing prose.