Repository navigation
Git Hooks and Release Gates
Canonical source:
rules/23-git-commits-hooks-and-release-gates.md— this page is rendered from it on every publish; edit the source.
Quality gates run where they are cheap and correct. The hooks prove the change itself, fast; CI proves it against the whole repository; release runs only on a green CI. This rule is the single canonical home for how a change lands and what each gate runs. Every other file links here instead of restating it.
Every commit and push in the repo; .husky/*; tools/gates/*; tools/affected/*;
.github/workflows/*.
npm run affected:list # which workspaces your change touches, and why
git add <explicit paths> # never -A, never .
git commit # the hook gates the staged change (see the matrix)
git push origin <branch> # the hook gates every pushed ref's tree; then CIThat is the whole loop. An agent runs nothing else by hand for a normal
change: the hooks run the right gates for the change type, scoped to what
changed, and CI runs the rest. Optional, when you want one proof up front
instead of two hook runs: npm run gates:receipt after staging — it runs the
hook gates over the staged tree once and records what passed, so the hooks skip
exactly those gates for exactly that tree
(rules/34 rule 4).
Before release: npm run release:preflight runs the all-workspace gate.
pre-commit (staged changes only):
-
lint-staged—eslint --fix --max-warnings 0(content cache) andprettier --writeon the staged files. Touching a file means leaving it with zero warnings. The two run in sequence on each file, Prettier last, because lint-staged runs separate globs concurrently and a lateeslint --fixonce re-wrote a formatted file (CI's formatting ratchet then failed). The CIPolicyjob is advisory: it never blocks Release. - Secret scan —
gitleaks git --stagedwith.gitleaks.toml. Without gitleaks installed it warns loudly and continues; CI scans every commit. - Auto-sync (
tools/gates/autosync.mjs, ADR-202) — prunes format/lint baseline entries that can no longer apply, records declared coverage thresholds, and pins a newly advisory'd production dependency (tools/security/audit-fix.mjs, throttled to 6 h). Each fix is staged and printed as anautosync:line. Baselines only shrink; nothing is weakened. - Knowledge layer — regenerate
.ai/**, workspaceAGENTS.mdand the inventory snapshot, stage them, verify links, docs and contradictions (rules/24); records aknowledgereceipt for the staged tree. - Root checks + typecheck — a lockfile change runs
npm ci --dry-run; an ESLint config change runsarchitecture:checkand lints real files; a root tsconfig change typechecks the workspaces extending it. Then every workspace the staged change affects is typechecked, after any stale shared package is rebuilt in dependency order.
commit-msg — commitlint (conventional subject, body lines ≤ 200) and
docs:impact: a Docs: trailer, and the docs of every mapped code area the
commit touches (rules/63).
pre-push (tools/gates/pre-push.mjs; before the gates, tools/gates/self-heal.mjs
commits a stale generated tree as chore(knowledge): refresh generated files and a
pending dependency pin as chore(deps) through the normal hooks, then stops once so
you re-run git push; it scaffolds, never fills, a missing QA record; every pushed ref read from stdin; base
resolved as origin/HEAD → origin/main → main, fetched if missing, never
guessed; a stacked branch sets CLAW_GATE_BASE=<parent branch>):
-
knowledge:verify+audit:check— skipped when pre-commit's receipt covers the tree. - Root checks again, plus
npm run knowledge:test:fastwhentools/,scripts/,eslint/or.husky/changed, andarchitecture:checkwheneslint/changed. - Typecheck of the workspaces that depend on a changed shared package.
- Tests of the directly changed workspaces —
vitest relatedwhen only source undersrc/changed, the whole suite otherwise. - Build of the directly changed workspaces.
A pushed ref whose tree is not checked out passes only when receipts cover all
five gates for its tree. Workspaces run in a bounded pool (CLAW_GATE_JOBS).
| Change type | pre-commit | pre-push | CI (ci.yml + ai-native-os) |
By hand |
|---|---|---|---|---|
Docs only (*.md anywhere) |
prettier, secret scan, knowledge + docs checks (rules/63). No code gate. | knowledge (skipped via receipt). No code gate. | knowledge freshness + integrity (docs checks), format ratchet, secrets, CodeQL, QA evidence | nothing |
| Single-workspace source | eslint --max-warnings 0 + prettier, secret scan, knowledge, typecheck |
vitest related, build |
setup, static (lint ratchet + typecheck), test + coverage floor, changed-lines coverage, build, policy | nothing |
Shared package (packages/*) |
+ stale shared dist rebuilt in order; typecheck package + all dependents |
related tests of the package, typecheck of dependents, build of the package | the full matrix of every dependent | nothing |
| Prisma schema | typecheck of the service (against its current client) | related tests / suite, build | setup regenerates every client; static, test, build of the service |
npm run prisma:generate --workspace=<svc> and the migration (rules/52) |
Frontend (apps/claw-frontend) |
frontend eslint --max-warnings 0 + prettier, knowledge, typecheck |
vitest related, next build
|
as single-workspace, frontend suite sharded + merged coverage; lighthouse.yml
|
the browser lanes of rules/60 (Playwright, device matrix) |
| Root config or lockfile | root checks (npm ci --dry-run / ESLint config loads / tsconfig typecheck) |
root checks | every workspace (root invariant), npm audit
|
nothing |
CI or workflow (.github/**) |
prettier, secret scan, knowledge | tooling tests (workflow shape tests) | every workspace, actionlint + shellcheck, the new or changed jobs themselves | optional: actionlint locally |
Hooks or tools (.husky, tools, scripts, eslint) |
prettier, secret scan, knowledge | tooling tests (knowledge:test:fast), architecture:check for eslint/
|
every workspace, tooling tests, deploy rehearsal when deploy paths changed | nothing |
CI job by job, and how a red job blocks release:
docs/08-runtime-devops/ci-cd-pipeline.md.
- Let the hooks gate the change. Commit, let pre-commit run; push, let pre-push run. Do not pre-run the same gates by hand "to be safe" — that pays twice (rules/34). A hook failure is a real problem in what you staged: fix it.
-
--no-verifyis banned (ADR-061), as is any other hook bypass. A receipt skips only gates it ran. -
Conventional commits —
feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert, subject ≤ 100 chars, no sentence/start/pascal/upper case, body lines ≤ 200 chars, and aDocs:trailer (rules/63). -
Explicit paths when staging —
git add <path> …, nevergit add -A/.(it sweeps in parallel work). -
Push each commit before starting the next one. CI only sees what is pushed;
git log --oneline origin/<branch>..HEADmust be empty before you stage the next change. The only exception is an explicit user instruction not to push. -
Prefer reversible git actions — a new commit over an amend; confirm before
force-push or
reset --hard. -
A flaky test is quarantined, not retried — per
testing/flaky-test-policy.md. The hooks never re-run a failing suite.
-
--no-verify(or any hook bypass) on commit or push. - Running lint/typecheck/test/build across every workspace for a scoped change.
- Re-running by hand the gates the hooks are about to run on the same tree.
-
git add -A/git add .when staging. - Committing again while an earlier commit is unpushed.
- A non-conventional commit subject, or a commit with no valid
Docs:trailer.
-
Hooks —
.husky/pre-commit,.husky/commit-msg,.husky/pre-push, delegating totools/gates/*andtools/affected/index.mjs. -
CI —
.github/workflows/ci.yml;CI successgatesrelease.yml. -
Tests —
tools/__tests__/gate-correctness.test.mjs,tools/__tests__/gate-receipt.test.mjs,tools/__tests__/affected-ci.test.mjs,tools/__tests__/ai-native-workflow.test.mjs,tools/__tests__/ci-gates.test.mjs. - Generated files — rules/24.
- rules/34 — receipts, concurrency, machine resources.
- rules/48 — testing and linting only what changed.
- rules/63 — docs move with code.
- skills/commit-and-push-each-change · skills/run-gates-once-and-land.
- Committed and pushed through the hooks; no bypass.
- Conventional subject, explicit paths, a valid
Docs:trailer. -
git log --oneline origin/<branch>..HEADis empty. - CI green, including
CI success.
ClawAI Wiki · source-controlled under wiki/ · generated/mirrored from the current repository knowledge layer.
ClawAI Wiki
Product
- Product-Vision
- Flagship-Features
- Business-Overview
- Requirements-Register
- Drift-Log
- Runtime-Managed-Connector-Providers
- Threads
- ADR-Index
Architecture
- System-at-a-Glance
- Architecture-Map
- System-Architecture
- Message-Flow
- End-to-End-Data-Flow
- Routing-Engine
- Event-Bus
- Security-Architecture
Platform
- Backend-Services
- Frontend-Architecture
- Shared-Packages
- Database-Reference
- API-Reference
- Provider-Catalog
- Memory-and-Context-Architecture
- File-Support-Architecture
- Research-and-Web-Crawling
Runtime & Ops
- Docker-Guide
- Nginx-Reference
- CI-CD-Pipeline
- Logging-and-Observability
- Operational-Runbooks
- Troubleshooting
Quality
Engineering OS
- AI-Native-Engineering-OS
- Generated-Manifests
- Rules-Catalog
- Skills-Catalog
- Context-Layer
- Engineering-Memory
- Tooling-and-Automation
- Scripts-and-Operations
- ESLint-and-Architecture-Enforcement
- Extended-Work-Skills
Agents
Reference