# Policies

A rule written in a standard is read by the model, which may follow it. A
policy is a rule a machine answers yes or no, at the moment of an action: a
commit, a push, an edit. The standard explains and prevents; the policy
refuses what escaped it. The same rule can live in both.

A policy acts at three points, from one file:

1. **Before generation.** Each enabled policy is listed under `## Policies`
   in the `AGENTS.md` block of the scope it applies to, so the agent is told.
2. **Before execution.** The Claude Code guard refuses an edit that adds a
   refused line, and a command that would skip the git hooks.
3. **Before git records.** Git hooks in every clone `rness.json` declares
   refuse the commit or the push, for any agent and for people.

## A policy

A policy is a Markdown file of `.rness/policy/`: `policy/<name>.md` applies
everywhere, `policy/<scope>/<name>.md` to one scope. The name is lowercase
words joined by hyphens and is the policy's id in every message. The title is
the `#` heading and the body is the reason, for the people who review it and
the agents that read it. Policies have no number: `rness doc new policy` is
refused.

```md
---
status: Enabled
standard: standards/documentation.md
rules:
  - check: commit-message
    deny: '\u2014'
    fix: Write " - ", a comma, a colon or a period instead of the em dash.
  - check: added-lines
    deny: '\u2014'
    fix: Write " - ", a comma, a colon or a period instead of the em dash.
---

# No em dash

Text with an em dash reads as machine-written. Use " - ", a comma, a colon
or a period.
```

| Key | Required | Value |
| --- | --- | --- |
| `status` | yes | `Enabled`: applied. `Disabled`: listed and validated, applied nowhere. |
| `rules` | yes | A non-empty list of rules. |
| `standard` | no | The path of a standard of the workspace that explains the rule. It must exist. |
| `date`, `updated` | no | ISO dates. |

Any other key is refused. Each rule has three keys, all required: `check`,
`deny` and `fix`. `fix` is one line: it is what the agent reads to correct
itself.

A `deny` pattern is a JavaScript regular expression, compiled with the flags
`i` (a trailer's case does not matter) and `u` (`\u2014` names the em dash
without writing it), and matched against one line at a time. `^` and `$` are
the line's. A scoped policy only adds to the global ones, and a name used both
globally and in a scope is refused.

`rness validate` checks every policy, disabled ones included, and names the
file and the line of what it refuses: an unknown key, a missing `status` or
`rules`, a rule without `check`, `deny` or `fix`, a pattern that does not
compile, a `standard` that does not exist, a name that is not lowercase words
joined by hyphens. It also refuses YAML anchors, aliases, custom tags, merge
keys and duplicate keys. The CLI package publishes a JSON Schema of the front
matter.

## The three checks

Rness provides a fixed set. A rule picks one; there is no condition and no
expression language.

| `check` | What it reads | `deny` | Run by |
| --- | --- | --- | --- |
| `commit-message` | Every line of the commit message, cut at git's scissors line only for a message edited in an editor (never under `-m`, `-F` or for a merge message). Comment lines are read too: under `-m` and `-F` git keeps them in the commit. | A pattern | The `commit-msg` hook |
| `added-lines` | Each line a commit or an edit adds, never a line already there. | A pattern | The `pre-commit` hook, and the guard on `Edit` and `Write` |
| `push` | Each ref update of a push. | `non-fast-forward`, the only value | The `pre-push` hook |

- **Added lines only.** A file that already holds the pattern does not block a
  commit that does not touch that line.
- **Merges.** A merge git concludes itself runs no `pre-commit`. One you
  conclude with `git commit` after a conflict does, and only the lines added
  against every parent are checked: your conflict resolutions and any new
  line. A line either branch brought passes, since it was checked when that
  branch committed it.
- **Rness's own outputs are not checked** by `added-lines`: the files under
  `.claude/skills/rness/` and the lines inside a rness block. Nobody can fix
  them where they land; their source is elsewhere.
- **Non-fast-forward** means the remote object is not an ancestor of the local
  one. Whatever the flag (`-f`, `--force-with-lease`, `+main`, an alias), the
  push is judged on what it does. A new branch passes, and so does a deletion.
  A remote object missing locally reads as non-fast-forward, and the fix says
  to fetch first.
- **Several scopes in one clone** (a monorepo): `added-lines` applies the
  policies of each file's own scope, the deepest one holding it;
  `commit-message` and `push` apply those of every scope of the clone.

## The git hooks

`rness create`, `rness add` and `rness sync` write three hooks, `pre-commit`,
`commit-msg` and `pre-push`, in the hooks directory of every clone under
`org/` that `rness.json` declares: the repositories of `scopes`, whose parts
share their repository's hooks. They are local to your machine and never committed to the project.
They are written whatever the policies, and each passes at once while no
enabled policy uses its check: a policy enabled in `.rness/` applies as soon
as the clone has pulled it, with no `sync`. `.rness/` itself gets the same
three through its own `.githooks/`.

A clone `rness.json` does not declare gets no hook, and no policy applies in
a clone that holds no scope: nothing is checked there, by the hooks or by the
guard. A clone's name is compared whatever its case, so `org/Web` is the
declared `web` and its policies apply.

Each hook carries a marker line and runs the CLI pinned in
`.rness/package.json`, by the workspace's absolute path. `rness sync`
rewrites a rness hook that is missing or out of date. It reports two cases,
once per clone until the cause changes, and writes nothing there:

- a hook file without the marker is someone else's and is left as it is;
- a clone with `core.hooksPath` set (husky, lefthook) is left alone.

Each report ends with the lines to add to that hook, or to each of the three
hooks of your own hook manager, `<hook>` replaced by the hook's name. They
find the workspace from the clone, two levels up, so your team can commit
them; outside a work tree they do nothing, and they end the hook only to
refuse, so your own lines after them still run:

```sh
rness_dir=
if rness_top=$(git rev-parse --show-toplevel 2>/dev/null); then
  rness_dir=$(cd "$rness_top/../../.rness" 2>/dev/null && pwd -P) || rness_dir="$rness_top/../../.rness"
fi
rness_bin="$rness_dir/node_modules/@rness/cli/dist/bin/rness.js"
rness_why=
if [ -z "$rness_dir" ]; then
  :
elif ! command -v node >/dev/null 2>&1; then
  rness_why='node not found'
elif [ ! -f "$rness_bin" ]; then
  rness_why="$rness_bin not found"
elif [ ! -f "$rness_dir/rness.json" ] || [ ! -O "$rness_dir" ] || [ -n "$(find "$rness_dir" -prune -perm -0002)" ]; then
  echo "rness: policies not checked: $rness_dir is no workspace .rness of yours alone" >&2
else
  rness_status=0
  rness_out=$(node "$rness_bin" policy check <hook> "$@" 2>&1) || rness_status=$?
  if [ "$rness_status" -ne 0 ] && [ "$rness_status" -ne 20 ]; then
    rness_out="rness: policies not checked: the rness CLI exited $rness_status"
  fi
  if [ -n "$rness_out" ]; then
    printf '%s\n' "$rness_out" >&2
  fi
  if [ "$rness_status" -eq 20 ]; then
    exit 1
  fi
fi
if [ -n "$rness_why" ] && { [ ! -d "$rness_dir" ] || grep -rqsE "^status:[[:space:]]*[\"']?Enabled" "$rness_dir/policy"; }; then
  echo "rness: policies not checked: $rness_why" >&2
fi
```

The hooks fail open. A missing `node`, a pinned CLI not installed, a `.rness/`
not reachable (a standalone clone) or an error of Rness's own never blocks a
commit: the hook prints one line, `rness: policies not checked: <why>`, and
lets git go on. A missing `node` or CLI says nothing while no policy is
enabled, since nothing would be checked. Only a refusal blocks: its message
is shown, and the hook exits 1. Any other exit of the CLI is one line,
`rness: policies not checked: the rness CLI exited <n>`, in place of what
it printed.

A hook runs the CLI only from a `.rness/` that holds its `rness.json`, is
owned by you and is not writable by everyone. A `.rness/` someone else could
have placed above a clone (`/tmp/.rness` for a clone under `/tmp`) is never
run: the hook says so in one line.

**Removing the hooks**

A rness hook is the one whose second line is the marker,
`# rness: policy hook`. After moving the pin back to a version without
policies, each commit says `the rness CLI exited 2` until you remove them.
In each clone:

```sh
for hook in pre-commit commit-msg pre-push; do
  file="$(git rev-parse --git-path hooks)/$hook"
  if grep -qs '^# rness: policy hook' "$file"; then rm "$file"; fi
done
```

A hook without the marker is left as it is.

## The refusal

The message is written for the agent that has to fix it alone. It names every
failing rule of every policy, so one correction passes:

```
rness: policy no-agent-trailers refused this commit
  commit message, line 7: Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
  fix: Remove the agent's Co-Authored-By trailer, then commit again.
  policy: .rness/policy/no-agent-trailers.md
```

Each failing rule shows where (the message line, `path:line` for an added
line, or the ref for a push), the offending line cut to 120 characters, its
`fix`, and the standard when the policy names one. A git hook prints it on
stderr and exits 1, which the agent sees as its command failing; the guard
prints the same text and refuses the tool call. There is no retry limit.

## Where refusals show

Each refusal is recorded as one line in `rness/refusals.jsonl`, in the git
directory of the clone or of `.rness/`: never committed, never pushed, and
pruned to 30 days by `rness sync`.

- **The session summary.** With a board that keeps a [journal](./boards.md),
  the summary of a session gains a line such as
  `Policies: 3 refusals (no-em-dash 2, no-agent-trailers 1)`, and is posted
  when the session has at least one commit, note or refusal. Two sessions in
  the same clone at the same time both count the same window.
- **`rness status`.** A Policies tab lists every policy with its scope and
  status, then the refusals of the last 7 days across the clones, grouped by
  policy with the count and the last time, in UTC. `/rness:status` shows the
  same.

## Turn on the example

A new workspace has no enabled policy. It ships one example, disabled:
`policy/no-force-push.md`, which refuses a push that rewrites a remote
branch. To enable it, change one line in `.rness/policy/no-force-push.md`:

```diff
-status: Disabled
+status: Enabled
```

Commit it to `.rness/` and merge it as any change. Each clone applies it once
it has pulled `.rness/`; `rness sync` then lists the policy in the blocks.
Write your own the same way: a file, its rules, its reason.

## What enforces it

Dated 2026-11-03. Informed means the block of `AGENTS.md` tells the agent.

| Who | Informed | Blocked before the action | Not covered |
| --- | --- | --- | --- |
| Claude Code, local | Yes | The guard: the lines an edit adds, a bypass of the hooks. The git hooks: commit, push. | A write made through Bash (`sed -i`) until it is committed; a hook that errors (it fails open); the cases listed below. |
| Codex CLI, Cursor, local | Yes, through `AGENTS.md` | The git hooks: commit, push. | `--no-verify`; a write until it is committed. |
| Cloud agents (Codex cloud, Cursor background agents, Claude Code on the web) | If they read `AGENTS.md` | Nothing: no Rness hook in their clone. | Everything else. |
| A person | No | The git hooks. | `--no-verify`. |
| A clone using husky or lefthook | As its harness | Nothing until the team adds the lines `rness sync` prints. | Everything else. |

For Codex CLI and Cursor, the git hooks apply by inference: their documentation
says nothing of git hooks (verified 2026-11-03), and a shell they start runs
the clone's hooks as any shell does. A pull request description and a comment
on the host never pass through git: no policy reaches them.

### What the Claude Code guard does not see

On `Bash`, the guard reads every command and refuses a bypass of the git
hooks while an enabled policy applies: `git commit --no-verify` or `-n`,
`git push --no-verify`, `git merge` or `git pull --no-verify`,
`git -c core.hooksPath=...`, an alias that skips hooks, `GIT_CONFIG_GLOBAL`,
`GIT_CONFIG_SYSTEM`, `GIT_CONFIG`, and a write of `core.hooksPath` or of an
include. When a git command holds a hook-skipping word it cannot read, it
refuses as a backstop, so it can refuse a command that was harmless
(`GIT_CONFIG_GLOBAL=/dev/null git commit`, `git -c "$KV" ...`, `ls *.md commit -n`). The git hooks
still run in every case below except the last two groups, which change or
route around the hooks themselves.

**The cases it does not catch**

- **Scripts it cannot see.** A shell reading its script from stdin or a file
  (`bash <<EOF`, `... | sh`, `sh < file`, `bash script.sh`, `source file`, `. file`); shell functions
  and aliases; other interpreters (`python -c`, `node -e`, `perl -e`), `make`,
  `npm run`, any script that runs git.
- **Configuration it cannot see.** An alias value is read as a shell reads it, not with git's own splitting. Git aliases already in a configuration
  file or in the hook's own environment; another global configuration through
  `HOME=` or `XDG_CONFIG_HOME=`; `GIT_EXEC_PATH` or `--exec-path=` pointing git
  at other commands.
- **Values it cannot read.** An unknown expansion among the arguments of
  `commit`, `push`, `merge` or `pull` that no option takes
  (`git commit $(printf -- --no-verify) -m x`) is skipped; only the backstop,
  for a command not read to the end, counts it.
- **Options of another git.** An option the tested git (2.56.0) does not know,
  combined with `-n` rather than a literal `--no-verify`.
- **Wrappers.** `-n` behind a wrapper the parser does not know, unless it
  follows `commit` (`parallel git commit -n`).
- **Places.** A command started outside any workspace whose git target cannot
  be placed (`cd "$X" && git commit -n` from `/tmp`).
- **Shell readings.** Only bash 3.2 and zsh were run against the reader.
  Some zsh patterns, a brace expression whose separator comes from an
  expansion, and bash 5, dash or fish where they differ from both.
- **False positives.** The backstop fails closed, so it can refuse a
  harmless command: `ls *.md commit -n`, `git commit -m x *` (refused as
  "may", since the shell could expand `*` to an option).
- **Policies.** An `extends` cycle makes the Bash check fail open, as the git
  hooks do; `rness validate` reports it.
- **Commits that run none of these hooks by design.** `git commit-tree` with
  `git update-ref`, `git am`, `git rebase`, `git cherry-pick`, `git revert`,
  `git stash`; a merge git concludes itself runs no `pre-commit` (one you
  conclude with `git commit` after a conflict does).
- **The hooks themselves.** `rm`, `chmod -x` or an edit of `.git/hooks/*`, an
  edit of `.git/config` (the edit tools or `echo >>`), `git config --unset`
  of a team hook manager's path.
- **Git's own state written by hand.** A `.git/MERGE_HEAD` naming a commit
  that holds a refused line: at the merge conclusion, that line passes as a
  branch's own.
