Git PR Workflow

Git hooks, commits, and PR flow

Hooks are managed by husky (core.hooksPath → .husky/_, installed by the prepare script in package.json). The repo CLAUDE.md "Git hooks" section summarizes the tiers; this skill covers what to do when a gate fires and the traps around commits, worktrees, and merging.

Quick map

Pre-commit anatomy

.husky/pre-commit runs three tiers; a trap prints scripts/pre-commit-help.sh on any failure.

Tier 1 (parallel):

• npx lint-staged — per .lintstagedrc.json: src/**/*.ts gets eslint --fix + prettier --write + the pattern checker (scripts/check-patterns.ts); tests/**/*.ts gets eslint + prettier only; *.config.ts and *.md get prettier only. The pattern checker runs only on src/ files.
• npm run typecheck
• npm run check:boundaries:staged — the staged variant (scripts/check-layer-boundaries.sh --staged), not plain check:boundaries. On failure, see the architecture-navigation skill.

Tier 2: npm run test — changed-file tests on the occt-wasm kernel, no coverage thresholds (vitest run --project occt-wasm --changed). Set FULL_TESTS=1 to run npm run test:full (full suite with coverage) instead. Test failures: see the writing-tests skill.

Tier 3 (non-blocking, always exit 0):

• npm run check:readme-reminders — lists READMEs adjacent to staged .ts files that may need updating.
• bash scripts/check-function-lookup.sh — fires when a staged path matches src/**Fns.ts (any depth) or an index.ts at one directory level (src/index.ts or src/<dir>/index.ts) without docs/function-lookup.md. Act on this one: run npm run docs:generate-lookup and stage the result. The local reminder is soft and its index.ts match is shallow (a deeper src/kernel/occt/index.ts won't trip it), but CI's build job is the authoritative gate at any depth — it regenerates, prettier-normalizes, and git diff --exit-codes the file.

Before committing multi-file changes, prefer npm run validate (typecheck → lint → boundaries → format:check → changed tests) and read its output — do not commit on a partially green tree.

Bypass with git commit --no-verify only as a last resort; CI runs strictly more than the hook, so a bypassed failure just moves to the PR.

Note: scripts/pre-commit-help.sh and CONTRIBUTING.md still say coverage thresholds are enforced "at push time" / "in pre-commit hooks". That is stale — coverage thresholds run only in the main-branch-only, non-blocking coverage CI job. Locally they run only via npm run test:full.

commit-msg and pre-push

• .husky/commit-msg runs commitlint --edit with @commitlint/config-conventional. A rejected message means the format is wrong, not the content — fix the type(scope): subject shape.
• .husky/pre-push runs only npm run knip (unused-code detection, ~2 seconds). The full test suite is intentionally not re-run on push; CI's sharded test job is the full gate. If knip fails, either use the newly-flagged export or remove it — do not add it to knip.config.ts without cause.
• If a push looked odd (interrupted terminal, unusual delay), verify it landed: git ls-remote origin <branch>.

Commits

Format: type(scope): subject. Types and examples: CONTRIBUTING.md "Commit Conventions" (feat, fix, docs, style, refactor, perf, test, chore).

The ! breaking-marker trap. In release-please-config.json, the root brepjs package excludes apps and every packages/* workspace, so satellite-only commits never touch the root version. Everything else at the repo root — including docs/, scripts/, and CI config — feeds the root release. Any commit with ! (or a BREAKING CHANGE: footer) touching those paths major-bumps the published brepjs library. Never put ! on site, docs, or tooling commits. When a change genuinely is breaking, confirm it touches the library surface (src/) before marking it. Full release pipeline: release-publishing skill.

Branches and worktrees

• Branch naming: <type>/<kebab-description> where type is the conventional-commit type of the work — feat/judge-graded-reference-verdict, fix/memory-leak, docs/api-examples. (CONTRIBUTING.md shows an older feature/ prefix; current practice uses the commit type.)

• Worktrees for parallel branches go under .worktrees/<branch> inside the repo — gitignored (.gitignore) and excluded from the root vitest suite (vitest.config.ts excludes .worktrees/** and .claude/worktrees/**, because a stale worktree copy without WASM set up would otherwise fail the root suite):

  git worktree add .worktrees/feat-my-change feat/my-change

• Run gh pr merge from the main repo path, never from inside the worktree — deleting the branch while its worktree has it checked out fails.

• After merge: git worktree remove .worktrees/<branch>, then in the main tree git checkout main && git pull. The repo deletes branches on merge, so the local branch goes [gone]; prune with git fetch --prune.