# The rat-stack bestiary eats excuses

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [effect-discord-perms](/news).

[ShitRat](/lore/shitrat)'s field guide keeps two labels on each specimen.
**Habitat** points to its real rule or implementation.
**Legend has it…** supplies the temperament, teeth, and dubious eating habits.

## The fence

**Habitat:** [the fence](/lore/the-fence), with checks in `oxlint.config.ts` and hooks in `lefthook.yml`.
It uses compiler checks, lint, tests, and hooks to enforce repo rules.
It rejects prohibited shortcuts; the [reference page](/lore/the-fence) also documents limits to what lint can prove.

**Legend has it…** the fence is a kelpie made of semicolons.
It cannot understand your startup pitch.
It can smell “just this once” through a closed laptop.

## The comment ban

**Habitat:** [No comments](/lore/no-comments), enforced by `scripts/oxlint-plugin-no-comments.ts`.
Prose comments are banned because agents copy explanations of workarounds.
The [policy](/lore/no-comments) keeps reasoned tool directives, safety invariants, and JavaScript type tags.

**Legend has it…** this creature nests beside TODOs and eats the explanation first.
If the workaround survives, it comes back for you.
It has never once accepted “self-documenting” as a snack.

## The gardener

**Habitat:** [Gardener](/skills/gardener), in `skills/gardener/SKILL.md`.
It calls for a failing rule or test before cleanup, then fixes existing instances.
The [procedure](/skills/gardener#4-remove-prohibited-patterns) also requires breaking the rule once to check the test, and keeps baselines shrink-only.

**Legend has it…** the gardener carries secateurs and a tiny black book titled THINGS YOU SAID WERE TEMPORARY.
The book has wheels now.

## The doc-fence

A doc-fence is a published TypeScript code block that the content build writes out and `pnpm check` typechecks.
**Habitat:** [the wiki authoring rules](/skills/write-a-wiki-page#4-quote-code-from-its-source), backed by `apps/site/scripts/doc-fences.ts`.
An authored TypeScript example without a source path must typecheck unless it declares a reasoned opt-out.
The [opt-out count](/lore/code-snippets#the-authoring-syntax) lives in `.brain/data/doc-fence-baseline.json` and only shrinks.

**Legend has it…** the doc-fence is a very small barrister living between three backticks.
It has cross-examined your illustrative snippet.
Your illustrative snippet has requested a solicitor.

## The startup ceiling

**Habitat:** [`apps/site/STARTUP.md`](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/apps/site/STARTUP.md).
It counts JavaScript in the static startup graph, including each shared module once.
At this revision, Mischief's shrink-only ceiling is **1,114,000 bytes**.
A [total upload above 2,500,000 bytes](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/apps/site/STARTUP.md) warns; that measurement does not itself fail the size gate.

**Legend has it…** the ceiling is a python that swallowed a tape measure.
It knows exactly how large your “small helper” is.
Do not offer it a larger building.

## Mischief

**Habitat:** [the site's Worker](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/apps/site/src/worker.ts), in `apps/site/src/worker.ts`.
The [rename commit](https://github.com/joelhooks/rat-stack/commit/246600bd53978883a6a4c1f5a6ff45e3f1ff2f0c) moves `apps/mischief` to `apps/site` and renames the package to `@rat-stack/site`.
Worker names, resource IDs, and TypeScript symbols retain their names.
Mischief therefore survives the directory rename.

**Legend has it…** Mischief changed the brass plate on its office and continued answering to the old name.
The forwarding address is a technicality.
The rat inside is still eating the stationery.

## The Git snapshot

The Git snapshot is the content build's stored Git query results and source fingerprints.
**Habitat:** [`apps/site/scripts/git-snapshot.ts`](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/apps/site/scripts/git-snapshot.ts), with data in `.brain/data/git-snapshot.json`.
Changed query output or a source fingerprint mismatch causes a stale-snapshot error.
[The snapshot dance](/lore/shitrat-rituals#the-snapshot-dance) gives the repair sequence.

**Legend has it…** the snapshot is a possum holding yesterday's newspaper.
You may have changed the world.
It would like you to update the bloody newspaper.

## Keep or cut

**Habitat:** [Keep or cut](/skills/keep-or-cut), in `skills/keep-or-cut/SKILL.md`.
It gives deletion recipes and asks you to check imports and tests before removing files.
One [dependency it names](/skills/keep-or-cut#cut-mcp): cutting [MCP](/lore/mcp-is-another-surface) also cuts [code mode](/lore/one-program-can-replace-several-tool-calls), which imports its toolkit code.

**Legend has it…** Keep or cut is a wheelie bin with excellent taste.
It has heard that you might need this someday.
It has opened its lid.

Learn [the rituals](/lore/shitrat-rituals), visit [the letterbox](/lore/shitrat-rat-king), or return to [the hub](/lore/shitrat).

## Sources

1. [Repo law at 81e9a31](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/AGENTS.md)
   rat-stack. The fence, comment policy, gardener rule, and required validation. Accessed 2026-11-07.

2. [Gardener](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/skills/gardener/SKILL.md)
   rat-stack. Write and break the rule before cleanup; baselines only shrink. Accessed 2026-11-07.

3. [Write a wiki page](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/skills/write-a-wiki-page/SKILL.md)
   rat-stack. Published TypeScript examples, pinned references, explicit opt-outs, and their shrinking baseline. Accessed 2026-11-07.

4. [Startup budget](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/apps/site/STARTUP.md)
   rat-stack. Static startup set, shared-module counting, Mischief ceiling, and total-upload warning. Accessed 2026-11-07.

5. [Move apps/mischief to apps/site](https://github.com/joelhooks/rat-stack/commit/246600bd53978883a6a4c1f5a6ff45e3f1ff2f0c)
   rat-stack. Mechanical directory and package rename; resource IDs, Worker names and symbols remain unchanged. Accessed 2026-11-07.

6. [Git snapshot implementation](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/apps/site/scripts/git-snapshot.ts)
   rat-stack. Stored Git query results, source fingerprints, and stale-snapshot failures. Accessed 2026-11-07.

7. [Keep or cut](https://github.com/joelhooks/rat-stack/blob/81e9a318e6ce3e767c62be6c2505605bfbb1f021/skills/keep-or-cut/SKILL.md)
   rat-stack. Deletion recipes, import checks, and the dependency from code mode to MCP. Accessed 2026-11-07.

## Lore on this page

- [The fence](/lore/the-fence)
- [No comments](/lore/no-comments)

## Linked from

- A rat can be a name with a mailbox → Rat King's named mailboxes and leased readers give ShitRat a postal mythology with a clear line between the rules and the rats' stories. → [Read page](https://ratstack.sh/lore/shitrat-rat-king)

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- ShitRat is Joel's familiar, with receipts → Meet ShitRat: Joel's terminal-dwelling familiar, its public house, its rules, its commits, and the incidents that became canon. → [Read page](https://ratstack.sh/lore/shitrat)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)

- The rat has rituals for proving it happened → The gate, the snapshot dance, receipts before claims, and the deployment check give rat-stack's folklore some repeatable steps. → [Read page](https://ratstack.sh/lore/shitrat-rituals)

- The war stories → Seven public repo incidents: a deploy undoes itself, failure says 200, sessions forget their guests, and the rat tests the demolition instructions. → [Read page](https://ratstack.sh/lore/shitrat-war-stories)

## Unlinked mentions

- [Agent rules for rat-stack (AGENTS.md)](https://ratstack.sh/AGENTS.md) → 0 — Do it: Fix your own red CI, failing hook, or stale git snapshot.