# Fence

> 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: [Foldkit 0.171.0 requires result Message schemas](/news).

## What it does

The fence is the compiler checks, lint rules, and hooks that reject prohibited code and shortcuts. [The fence](/lore/the-fence) explains the idea.
Effect describes work with typed failures and required services. A service is a named interface for one job.

XState `6.0.0-beta.3` defines state machines: named states and the events that permit movement between them.
`@xstate/effect` `1.0.0-beta.2` runs them as scoped Effects and supplies the compiled inline-Effect lint rule.
These checks enforce it today:

- Type-aware Oxlint runs Ultracite's core rules and the repo's plugins in `scripts/oxlint-plugin-*.ts`. The plugins cover boundaries, patterns, no comments, Effect tests, and XState with Effect. Vendored anti-slop rules also run. All use `error` severity in `oxlint.config.ts`.
- `rat-stack-boundaries/no-core-adapters` keeps provider adapters out of core. An adapter implements an application-owned interface for a specific provider.
- Ports, interfaces named for application jobs, stay in core. [Fixture tests](https://github.com/joelhooks/rat-stack/blob/main/packages/core/test/boundaries-rule.test.ts) prove the import boundary.
- Effect language-service diagnostics, compiler messages about Effect code, are set to `error` in `tsconfig.base.json`. `effect-tsgo patch` runs in `prepare`, so both `tsc` and the editor report failures.
- `@yielded/effect-tsrs` `0.2.3` runs TypeScript and Effect diagnostics in `typecheck` and `check`. Every invocation uses `--strict --type-check`. `--type-check` includes ordinary TypeScript diagnostics; `--strict` makes Effect warnings fail.
- effect-tsrs bundles tsrs `8f135f106a63`, contained in plain tsrs `0.20.0`.
- Plain [tsrs](https://blog.cloudflare.com/typescript-rust-port/) `0.25.0-ts7.1.0-beta` stays in `typecheck:fast`, targeting TypeScript `7.1.0-beta`. It still has no Effect diagnostics; use `typecheck` or `check` for those.
- Patched TypeScript `7.0.2` with `@effect/tsgo` `0.69.0` runs through `pnpm typecheck:tsc` at the switch and on checker bumps. CI does not run it. `ignoreEffectWarningsInTscExitCode` stays false.
- Report any checker disagreement.
- Lefthook runs `pnpm check` and `pnpm test` before every commit.
- `scripts/vcs-command-policy.js` blocks every way an agent command could skip or disable the hooks: `--no-verify` and its abbreviations, `git commit -n` (including flag clusters such as `-nm`), `LEFTHOOK=0`, `LEFTHOOK_EXCLUDE`, `HUSKY=0`, a `core.hooksPath` override, `lefthook uninstall`, and writes under `.git/hooks`, also inside `bash -c` or `sh -c`. It reads the command with shell quoting, so a commit message that mentions `-n` still passes. The Pi extension, the Claude Code hook, and the Cursor hook all call that one file.
- Continuous integration (CI) runs `pnpm turbo run check test build` after a fresh dependency install.
- The install uses the exact versions in the lockfile; it cannot update that file.

## The standard

- A commit runs check and test, and a failure stops it.
- No agent harness configured in the repo can skip or disable the hooks, with `--no-verify` or any other bypass.
- Effect diagnostics fail the typecheck.
- `pnpm bump:checkers` compares effect-tsrs and patched `tsc` errors, including Effect `TS377xxx`, for every package and root scripts. It normalizes paths, ignores suggestions and messages, and compares exit verdicts.
- The same command compares plain tsrs with patched `tsc`, excluding Effect-only codes. Plain tsrs cannot emit those diagnostics.
- Code carries no prose comments. Tool directives need a reason after `--`; type assertions need a one-line `SAFETY:` statement of the condition that makes the assertion safe. Plain JS may keep type-only JSDoc. [No comments](/lore/no-comments) and [repo law](/AGENTS.md) give the full exception policy.
- Every lint or diagnostic override names its rule and gives a reason.
- Prefer fewer overrides; adding one is allowed with a one-line reason in the PR. The [debt ledger](/debt.md), a report counting lint and diagnostic exceptions, publishes the count by kind.
- A new lint rule ships with a test that runs real Oxlint against fixtures.
- Loosening any of this needs the owner's sign-off.

## How to check

- `pnpm turbo run check test build` runs the main gate.
- `pnpm typecheck` runs strict effect-tsrs diagnostics.
- `pnpm typecheck:tsc` runs the patched compiler.
- `pnpm typecheck:parity` compares checker errors and exit verdicts. `pnpm bump:checkers` runs it on every bump.
- `pnpm typecheck:fast` runs plain tsrs for fast feedback without Effect diagnostics.
- `echo '{"tool_name":"Bash","tool_input":{"command":"git commit --no-verify"}}' | node scripts/hooks/block-git-no-verify.mjs` prints a `deny` decision with the reason.
- `pnpm --filter @rat-stack/core test` runs the fixture tests for the boundary, pattern, no-comment, and unknown-parameter rules, and the command policy test.
- The boundary fixtures in `packages/core/test/boundaries-rule.test.ts` reject adapter imports from core and accept composition outside it.
- `curl -sS https://ratstack.sh/debt.md` shows the current override count.

## Sources

1. [rat-stack/oxlint.config.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/oxlint.config.ts)
   GitHub joelhooks/rat-stack. Lint configuration; used for the enforced rule groups. Accessed 2026-10-01.

2. [rat-stack/tsconfig.base.json at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/tsconfig.base.json)
   GitHub joelhooks/rat-stack. Compiler configuration; used for Effect diagnostics at error severity. Accessed 2026-10-01.

3. [rat-stack/lefthook.yml at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/lefthook.yml)
   GitHub joelhooks/rat-stack. Commit hooks; used for the pre-commit check and test gate. Accessed 2026-10-01.

4. [rat-stack/scripts/vcs-command-policy.js at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/scripts/vcs-command-policy.js)
   GitHub joelhooks/rat-stack. Command policy; used for the shared hook-bypass prohibition. Accessed 2026-10-01.

5. [rat-stack/scripts/hooks/block-git-no-verify.mjs at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/scripts/hooks/block-git-no-verify.mjs)
   GitHub joelhooks/rat-stack. Harness hook; used for the failing bypass check. Accessed 2026-10-01.

6. [rat-stack/.github/workflows/ci.yml at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/.github/workflows/ci.yml)
   GitHub joelhooks/rat-stack. CI workflow; used for the cold-install validation gate. Accessed 2026-10-01.

## Lore on this page

- [The fence](/lore/the-fence)
- [Handle expected failures without hiding defects](/lore/error-model)
- [No comments](/lore/no-comments)

## Linked from

- 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 systems | rat-stack → The systems rat-stack ships, the standard each keeps, and how to check it. → [Read page](https://ratstack.sh/systems)

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