# Adopt catalog policies

Install policies from chock-catalog into your repository, pinned to a commit and checked against a hash, with the output of a real run.

The chock-catalog repository is the public catalog of chock policies. This page adds two of them to a fresh repository with \`chock add\`, compiles them with \`chock sync\`, and shows a commit refused by one of them. Every command and output below is from a recorded run.

> Ask the user before running any command on this page: each one changes how their agent or repository behaves.

## Two ways to adopt

There are two ways to install the same policies:

- **In your repository**, for a team: policies are pinned to a catalog commit, committed with the repository, and run at the agent's own hook where the client has one, at commit and in CI. This page walks through it.
- **In your coding agent, as plugins**, for one person with no repository changes. There are two ways, and you install a given policy from one of them only, never both, because every copy runs its own hook. The chock.sh builder makes one merged plugin per client and needs chock: ask first, then build it from a selection with `chock install --selection <code> --apply`. See [Quickstart: plugin](https://chock.sh/docs/quickstart/plugin/index.md). If you cannot install chock, the per-policy marketplace needs Python 3.11+, git and a bash but no chock, and carries one plugin per policy: the README's [Install section](https://github.com/open-coder-ai/chock-catalog/blob/1e60d211c1bb767152c6ab0167932da06ab3a10f/README.md#install) links each agent's repository.

## Adopt in your repository, step by step

A real run, recorded by `python -m sitegen.catalogdoc` with the engine and the catalog at the pinned commits. The steps of `data/catalog-adopt.yaml` ran in order in one fresh git repository at `/work/demo`, made with `git init -b main` and a git user name and email set, with HOME at `/home/demo`. Those paths stand for the throwaway folders the run used. Output is stdout and stderr together.

Step 1, exit code 0. Set up chock in the repository: git hooks, agent hooks, and the authoring skills. Ask the user before running the commands below:

```text
$ chock init .
Installed pre-commit dispatcher to /work/demo/.git/hooks/pre-commit
No git-pre-commit.sh policies found; pre-commit dispatcher unchanged
Installed pre-merge-commit dispatcher to /work/demo/.git/hooks/pre-merge-commit
No git-pre-commit.sh policies found; pre-merge-commit dispatcher unchanged
Installed pre-push dispatcher to /work/demo/.git/hooks/pre-push
No git-pre-push.sh policies found; pre-push dispatcher unchanged
Installed commit-msg dispatcher to /work/demo/.git/hooks/commit-msg
No git-commit-msg.sh policies found; commit-msg dispatcher unchanged
Registered SessionStart arm hook in .claude/settings.json
INDEX.md: ~257 tokens (chars/4, max 2000)
INDEX.md: ~257 tokens (chars/4, max 2000)
Implementation registered at /work/demo/.git/hooks/pre-commit.d/99-chock-validate
[PASS] All checks passed.
Initialized Chock in /work/demo
Agents: AGENTS.md + claude, copilot, gemini
Skills: eval, optimize, policy-init, validate (refresh with `chock install-skills .`)
Policies: none. This repo enforces nothing yet.
  1. copy a policy folder from https://github.com/open-coder-ai/chock-catalog (base/<id>/) into .agents/policies/<id>/
  2. chock sync --repo .
Verify anytime with:  chock check --only verify
```

Step 2, exit code 0. Copy `protect-main-branch` from the catalog at the pinned commit into `.agents/policies/`, and compile it. `chock add` prints the policy's sha256. Ask the user before running the commands below:

```text
$ chock add protect-main-branch --ref 1e60d211c1bb767152c6ab0167932da06ab3a10f
Added protect-main-branch to .agents/policies/protect-main-branch
  from https://github.com/open-coder-ai/chock-catalog at 1e60d211c1bb767152c6ab0167932da06ab3a10f
  sha256 b469c3dbab9a12a009e3ef995fcab99d468e1363da4892af9f1b3bbdcf24a173
INDEX.md: ~314 tokens (chars/4, max 2000)
Compiled. Run `chock sync --repo .` to activate commit-time enforcement.
```

Step 3, exit code 0. Add `scan-secrets` the same way, with `--verify-sha` naming the hash it must have. A different hash refuses the install. Ask the user before running the commands below:

```text
$ chock add scan-secrets --ref 1e60d211c1bb767152c6ab0167932da06ab3a10f --verify-sha c7cf363c6eb8a8ed47287beef9c06fe76dfd2d9c0ccc203fe74e32fba0e92a94
Added scan-secrets to .agents/policies/scan-secrets
  from https://github.com/open-coder-ai/chock-catalog at 1e60d211c1bb767152c6ab0167932da06ab3a10f
  sha256 c7cf363c6eb8a8ed47287beef9c06fe76dfd2d9c0ccc203fe74e32fba0e92a94
INDEX.md: ~428 tokens (chars/4, max 2000)
Compiled. Run `chock sync --repo .` to activate commit-time enforcement.
```

Step 4, exit code 0. Compile both policies, install the git hooks, register the agent hooks, and write the CI gate workflow to `.github/workflows/chock.yml`. Ask the user before running the commands below:

```text
$ chock sync --repo . --ci
Installed pre-commit dispatcher to /work/demo/.git/hooks/pre-commit
Registered 2 pre-commit policy implementation(s)
Installed pre-merge-commit dispatcher to /work/demo/.git/hooks/pre-merge-commit
Registered 2 pre-merge-commit policy implementation(s)
Installed pre-push dispatcher to /work/demo/.git/hooks/pre-push
Registered 1 pre-push policy implementation(s)
Installed commit-msg dispatcher to /work/demo/.git/hooks/commit-msg
No git-commit-msg.sh policies found; commit-msg dispatcher unchanged
Registered 2 PreToolUse/Stop hook(s) in .claude/settings.json
  claude_code: pre-tool: block+rewrite, best-effort, fail mode open (agentseam basis live-run, recorded 2026-09-07)
  claude_code: Untested: chock has not witnessed its hooks run in this client; the wiring follows agentseam's record. What you see there is wanted as evidence: open-coder-ai/agentseam issues labelled 'evidence wanted'.
Registered 2 hook entr(y/ies) in .gemini/settings.json
  gemini_cli: pre-tool: block+rewrite, best-effort, fail mode open (agentseam basis vendor-source, recorded 2026-08-28)
  gemini_cli: Untested: chock has not witnessed its hooks run in this client; the wiring follows agentseam's record. What you see there is wanted as evidence: open-coder-ai/agentseam issues labelled 'evidence wanted'.
Registered 1 agent hook(s) in .github/hooks/chock.json
  vscode_copilot: pre-tool: block+rewrite, best-effort, fail mode open (agentseam basis live-run-partial, recorded 2026-09-28)
INDEX.md: ~428 tokens (chars/4, max 2000)
Recompiled 2 policies
protect-main-branch:
  claude: enforced-at-commit
  copilot: enforced-at-commit
  gemini: enforced-at-commit
scan-secrets:
  claude: enforced-at-commit + best-effort at tool use (live-run)
  copilot: enforced-at-commit + best-effort at tool use (live-run-partial)
  gemini: enforced-at-commit + best-effort at tool use (vendor-source)
== install ci workflow
Installed CI workflow at /work/demo/.github/workflows/chock.yml
```

Step 5, exit code 1. Chock refuses a commit straight to `main`, and git exits 1. Ask the user before running the commands below:

```text
$ git commit --allow-empty -m notes
Direct commits/pushes to a protected branch (main|master) are blocked. Create a feature branch and open a pull request.
  - main
```

Step 6, exit code 0. Work on a branch instead. Ask the user before running the commands below:

```text
$ git switch -c adopt-chock
Switched to a new branch 'adopt-chock'
```

Step 7, exit code 0. Stage what chock wrote. Ask the user before running the commands below:

```text
$ git add -A
```

Step 8, exit code 0. The commit on the branch runs the hooks and lands. Ask the user before running the commands below:

```text
$ git commit -q -m 'Adopt chock'
== validate
[PASS] All checks passed.
== result: PASS
```

## Pin a commit and verify the hash

From the catalog docs: [README.md](https://github.com/open-coder-ai/chock-catalog/blob/1e60d211c1bb767152c6ab0167932da06ab3a10f/README.md)

### Installing this is running code

A policy here is not inert data. A declarative policy compiles to a git hook that runs on every commit in your repository; a policy shipping an `implementations/` guard becomes a guard script consulted before your agent runs a command; `java-security` and `no-a11y-regression` run their own program at commit and when the agent writes; `firecrawl-fallback-only` and `token-efficiency` run theirs before a matching tool call. Either way, `chock add` installs executable content over `git clone`. There is no signing key, so pin and verify when the catalog is not one you control:

Ask the user before running the commands below:

```bash
chock add scan-secrets --ref <commit-sha> --verify-sha <sha256>
```

This catalog has tags, but a tag can move: pin a full commit SHA. `--ref` refuses a commit that is on no branch or tag of the catalog; `--verify-sha` refuses the install unless the fetched pack hashes to the value you name.

Two limits worth knowing before you rely on any of this: `git commit --no-verify` skips every git hook, and git hooks are not cloned, so a fresh clone enforces nothing until someone runs `chock sync`. [SECURITY.md](https://github.com/open-coder-ai/chock-catalog/blob/1e60d211c1bb767152c6ab0167932da06ab3a10f/SECURITY.md) has the rest.

## Next

- Each policy's page under [Policies](https://chock.sh/docs/policies/index.md) lists what it refuses and how it was tested.
- The CLI reference has every option of [chock add](https://chock.sh/docs/cli/add/index.md) and [chock sync](https://chock.sh/docs/cli/sync/index.md).
- To write a policy for the catalog, see [Add a policy to the catalog](https://chock.sh/docs/catalog/contribute/index.md).


---

Built from engine [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) and catalog [1e60d211c1bb](https://github.com/open-coder-ai/chock-catalog/commit/1e60d211c1bb767152c6ab0167932da06ab3a10f).