Pre Commit Check

---
name: pre-commit-check
description: Use before committing or creating a PR for EmbodiChain to select proportional validation and verify affected code style, tests, headers, annotations, exports, and docstrings
---

# Pre-Commit Check

Run proportional local checks for the files being changed, catching relevant
issues before pushing without defaulting to the full test suite.

## When to Use

- Before creating a commit or PR
- User says "check my changes", "pre-commit", "verify before commit", "ready to push"
- After making any code changes to `.py` files

## Steps

### 1. Identify Changed Files

```bash
git diff --name-only HEAD
git diff --name-only --cached
git status --short
```

Collect all changed/added `.py` files.

Classify the change by affected area: workflow, docs, agent skill, packaged
configuration, isolated Python module, package-wide behavior, or cross-cutting
infrastructure.

### 2. Run Black Formatting Check

This is the **first CI gate** and will cause immediate failure:

```bash
black --check --diff --color ./
```

If it fails, run `black .` and review the formatting changes.

### 3. Check Public API Documentation Coverage

Run the same read-only gate used by CI:

```bash
python docs/scripts/check_api_docs.py
```

If it reports missing exports, use `$update-api-docs` to add useful Sphinx
entries and descriptions. Do not change `__all__` solely to make this check
pass.

### 4. Check Apache 2.0 Copyright Header

Every `.py` file must begin with the 15-line copyright block. For each changed/new `.py` file, verify the first line is:

```
# ----------------------------------------------------------------------------
```

The full header template:

```python
# ----------------------------------------------------------------------------
# Copyright (c) 2021-2026 DexForce Technology Co., Ltd.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ----------------------------------------------------------------------------
```

### 5. Check `from __future__ import annotations`

Every `.py` file must have this import (after the header, before other imports). This enables `A | B` syntax and forward references.

### 6. Check `__all__` in Public Modules

For any new or modified module under `embodichain/`, verify it defines `__all__` listing all public symbols. Example:

```python
__all__ = ["MyClass", "my_function"]
```

Skip this check for `__init__.py` files that only re-export via `from . import *`.

### 7. Check Docstrings on Public APIs

For any new public function, class, or method:
- Must have a Google-style docstring
- Must include `Args:` section if it takes parameters
- Must include `Returns:` section if it returns a value
- Use `.. attention::` or `.. tip::` directives for non-obvious behavior

### 8. Check Type Annotations

For any new public API:
- All parameters must have type hints
- Return type must be annotated
- Use `A | B` over `Union[A, B]`
- Use `TYPE_CHECKING` guard for imports that would cause circular dependencies

### 9. Check `@configclass` Usage

For any new configuration class:
- Must use `@configclass` decorator (not bare `@dataclass`)
- Must use `from dataclasses import MISSING` for required fields
- Import from `embodichain.utils import configclass`

### 10. Select and Run Relevant Tests

Do not treat the CI test job as a requirement to run `pytest tests` locally for
every change. Choose the smallest command set that exercises the affected
behavior:

| Change scope | Default validation |
|---|---|
| `.github/workflows/**` only | `actionlint` on changed workflows; run related script tests only when workflow scripts changed |
| Human-facing docs content only | Relevant Sphinx build or docs-specific tests |
| `agent_context/**` or its routing helper | Run `context.py check` and `tests/test_agent_context_{map,tools}.py`; exercise representative routes when routing changes |
| `.agents/skills/**` and thin adapters | Run `quick_validate.py` for each changed canonical skill; compile/run any bundled scripts |
| Task Program components/deployments | Run the `$add-task-program` static deployment inspector plus the closest configured-integration/package-data tests |
| Other packaged JSON/YAML | Parse through the production loader and run the closest config/layout tests |
| One Python module | Matching `tests/**/test_<module>.py` |
| One package/subsystem | Tests for that package plus focused integration tests |
| Packaging/release code | Package build and artifact validation |
| Shared core, global test config, or multiple subsystems | Broader affected tests; full suite only when narrow coverage is not credible |

Skip runtime tests when no executable behavior is affected, but still run the
appropriate syntax or configuration validator. Run the full suite only when:

- the change affects shared core behavior used throughout the repository;
- global dependencies, test configuration, or environment initialization changed;
- several subsystems are modified together;
- a release-critical behavior cannot be validated narrowly; or
- the user explicitly requests it.

Before starting a command likely to take more than two minutes, report the
selected scope and why narrower validation is insufficient. Honor explicit user
instructions to skip or narrow tests.

For canonical skill directories, use:

```bash
python "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \
  .agents/skills/<skill>
```

If the personal skill installation differs, locate the available `skill-creator`
validator through the session skill catalog instead of assuming a username.

Thin `.claude/skills/` and `.github/copilot/` adapters should point back to
the canonical `.agents/skills/<skill>/SKILL.md`; do not duplicate the full
instructions in adapters.

### 11. Check Test Coverage

For any new public module or function:
- A corresponding test must exist at `tests/<subpackage>/test_<module>.py`
- Test file must also have the Apache 2.0 header
- Report if tests are missing

### 12. Summary Report

Output a pass/fail summary:

```
Pre-Commit Check Results
========================
[PASS] Black formatting
[PASS] Public API docs coverage
[PASS] Apache 2.0 headers (5/5 files)
[FAIL] from __future__ import annotations — missing in: foo.py
[PASS] __all__ exports
[PASS] Docstrings on public APIs
[PASS] Type annotations
[PASS] @configclass usage
[PASS] Targeted tests — tests/foo/test_bar.py
[N/A] Full test suite — isolated change covered by targeted tests
[WARN] Missing tests for: bar.py

Fix the above issues before committing.
```

## What CI Checks

The project's CI pipeline (`.github/workflows/main.yml`) runs:

1. **lint** job: `black --check --diff --color ./`
2. **lint** job: `python docs/scripts/check_api_docs.py`
3. **test** job: proportional pytest groups after lint passes
4. **build** job: Sphinx docs build after lint passes

This skill always covers the relevant lint and structural checks, then selects
tests proportionally. It does not require reproducing the entire CI pipeline for
every local change.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Running `black` on only one file | Run `black .` on the whole project — CI checks everything |
| Forgetting test Apache header | Test files also need the 15-line copyright block |
| Using `Union[A, B]` | Use `A \| B` (with `from __future__ import annotations`) |
| Using bare `@dataclass` | Use `@configclass` from `embodichain.utils` |
| Missing `__all__` in new module | Add `__all__` with all public symbols |

## Quick Reference

| Check | Command/Method |
|-------|---------------|
| Black formatting | `black --check --diff --color ./` |
| Auto-fix formatting | `black .` |
| Public API docs | `python docs/scripts/check_api_docs.py` |
| Header check | Verify first line is `# ---...---` |
| `__future__` import | Grep for `from __future__ import annotations` |
| `__all__` export | Grep for `__all__` in module |
| Run targeted tests | `pytest tests/<affected-path>` |
| Run full tests | `pytest tests` only when the full-suite criteria above apply |