# Lifecycle in a repository The repo path from end to end. You author a policy, check it and sync it into hook files. Then each tool call, commit, push and CI run goes through the hook to a verdict and one log line. A person authors and syncs once. After that, every agent tool call, every commit and push, and every CI run goes through the files chock sync wrote. The agent's hooks and the git hooks reach the same gate runner, so a policy means the same thing in the session and at commit. > Ask the user before running any command on this page: each one changes how their agent or repository behaves. ## Diagram [This diagram as JSON](/api/docs/architecture/lifecycle.json) ## Components - **Author a policy** (Engine code): The chock new policy \ command writes a policy skeleton. A policy is one folder under .agents/policies/\/: a manifest, an optional deterministic script, and an eval suite. The policy-init skill writes one from an interview. Source: [chock/src/chock/scaffold/new.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/scaffold/new.py) - **`chock check`** (Engine code): Runs the repository's checks in order (validate, verify, evals, matrix, mechanisms, index, conflicts, baseline). The --only flag picks a subset. Source: [chock/src/chock/lifecycle.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/lifecycle.py) - **`chock sync`** (Engine code): Recompiles every installed policy, then writes each wired agent's hook file, the git hooks and INDEX.md. With --ci it also writes the CI workflow. Source: [chock/src/chock/scaffold/recompile.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/scaffold/recompile.py) - **`chock compile`** (Engine code): Runs the emitter for each hook point on the policy and writes the output to `.chock/compiled///`. A hook point with no output gets no folder. It also writes a coverage report. Source: [chock/src/chock/compile/compiler.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/compile/compiler.py) - **Agent hook files** (Generated file): One entry per hook, in each agent's own file and format. Every entry runs the same committed launcher command. Source: [chock/src/chock/hooks/in_agent_install.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/hooks/in_agent_install.py) - **Git hooks** (Generated file): A dispatcher in .git/hooks for pre-commit, pre-merge-commit and pre-push. It runs each policy's hook, which calls the vendored runner. Source: [chock/src/chock/hooks/data/dispatcher.sh](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/hooks/data/dispatcher.sh) - **CI workflow** (Generated file): With --ci, chock sync writes .github/workflows/chock.yml. It runs the same runner with --event ci over a pull request's base...head range. Source: [chock/src/chock/scaffold/install_ci.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/scaffold/install_ci.py) - **Compiled gates** (Generated file): Loads hook.gate from manifest.yaml and bakes one gate.json per hook point. Source: [chock/src/chock/gate/build.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/gate/build.py) - **Agent tool call** (The agent's client): Before a tool runs, and at a turn's end where wired, the client runs the hook with the call on stdin. Agentseam reads it as an Event and answers in the client's own dialect. What happens when a hook cannot run is agentseam's data, listed below. Source: [agentseam/src/agentseam/dispatch.py](https://github.com/open-coder-ai/agentseam/blob/683f95b5f2784dc3446acb1c91636ebc5ee7bee6/src/agentseam/dispatch.py) Agentseam's tier table at the release the engine pins, by fail mode: - No adapted pre-tool hook (10): Aider (none), Amp (unadapted), GitHub Copilot (Agent Plugins 1.0 marketplace bundle) (unadapted), DeepSeek Harness (dsh) (unadapted), Kilo Code (unadapted), Kiro (unadapted), OpenCode (unadapted), Replit Agent (unadapted), Roo Code (unadapted), Zed (none) - If the hook fails, the action goes through (14): Antigravity (block+rewrite), Claude Code (block+rewrite), Cline (block), OpenAI Codex CLI (block+rewrite), Devin (block+rewrite), Factory Droid (block), Gemini CLI (block+rewrite), Grok CLI (block), Junie CLI (block+rewrite), Kimi Code CLI (block), OpenHands (block), Tabnine CLI (block+rewrite), GitHub Copilot (VS Code agent mode / CLI) (block+rewrite), Windsurf (Cascade) (block) - What a failed hook does can be configured (3): Cursor (block+rewrite), goose (block), Mistral Vibe (block+rewrite) - **Launcher** (Engine code): Runs the first of git config chock.python, python3, python and py that runs Python 3.11+. With none it exits 2, never allow. Source: [chock/src/chock/hooks/data/launch.sh](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/hooks/data/launch.sh) - **Agent runtime** (Engine code): The file `.chock/bin/.py` holds agentseam's bundle plus chock's handler. A `--guard` call runs the policy's script. A `--gate` call asks the vendored gate runner. Source: [chock/src/chock/gate/runtime_bundle.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/gate/runtime_bundle.py) - **Gate runner** (Engine code): Evaluates a compiled gate, caps its verdict, and concludes with an exit code. It is assembled into .chock/bin/gate.py, the same runner the git hook and CI run. Source: [chock/src/chock/gate/runner/verdict.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/gate/runner/verdict.py) - **Decision log** (Local log): One line per hook decision. With repo hooks it is `/.chock/log/gate-events.jsonl`. With the plugin it is `~/.chock/log//events.jsonl`. It never raises, never changes the decision and never logs contents. Source: [chock/src/chock/gate/decision_log.py](https://github.com/open-coder-ai/chock/blob/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021/src/chock/gate/decision_log.py) ## Connections - Author a policy → `chock check`: Manifest, evals - `chock check` → `chock sync`: Then - `chock sync` → `chock compile`: Each policy - `chock compile` → Compiled gates: `gate.json` - `chock sync` → Agent hook files: Per agent - `chock sync` → Git hooks: Git hooks - `chock sync` → CI workflow: `--ci` - Agent hook files → Launcher: Runs - Agent tool call → Launcher: `stdin` - Launcher → Agent runtime: Python 3.11+ - Agent runtime → Gate runner: `--gate` - Git hooks → Gate runner: Commit, push - CI workflow → Gate runner: `--event ci` - Compiled gates → Gate runner: Reads - Agent runtime → Agent tool call: Verdict - Gate runner → Decision log: One line ## Main path The flow this diagram is about, in order: 1. Author a policy 2. `chock check` 3. `chock sync` 4. Agent hook files 5. Launcher 6. Agent runtime 7. Gate runner 8. Decision log ## Pinned sources Every box cites a file at these commits. CI fails the build if a cited path is missing at its commit. - `chock` @ [5a4b6287a46e](https://github.com/open-coder-ai/chock/commit/5a4b6287a46e07f9f856d9bbe10622bd1ff2e021) - `agentseam` @ [683f95b5f278](https://github.com/open-coder-ai/agentseam/commit/683f95b5f2784dc3446acb1c91636ebc5ee7bee6) --- 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).