Skip to content
This repository was archived by the owner on Nov 10, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .claude/skills/verify-change/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,18 @@ Use Python 3.14 and install all extras before proving a change:
`uv sync --all-extras --python 3.14` (also performed by `bin/setup`). CI selects
Python 3.14 and installs the editable package with `uv pip install -e ".[all]"`.

The two install paths do not resolve the same tool versions. CI's
`uv pip install -e ".[all]"` does not read `uv.lock`, so CI runs the newest
release inside pyproject's dev-extra ranges — `ruff>=0.16.1,<0.17` and
`mypy>=2.4.1,<2.5`. Local `uv sync --all-extras` and `uv run` do read `uv.lock`,
so they run the locked ruff 0.16.1 and mypy 2.4.1. A green local gate is
evidence for the locked versions only — it is not a guarantee that CI will pass.

`requirements.txt` is a committed `uv pip compile` output of `pyproject.toml`, so it floats to the newest in-range releases (fastapi 0.149.0 against the lock's 0.139.2, pydantic 2.14.1 against 2.13.4); only claude-agent-sdk, ruff and mypy are held at `uv.lock`'s resolution, and it is not a gate input.

The pre-commit hook installed by `scripts/setup-hooks.sh` runs `bin/check` and
propagates its exit status: a red gate blocks the commit.

| CI job | Local equivalent in `bin/check` |
|--------|--------------------------------|
| Lint | `uv run ruff check .`, `uv run ruff format --check .`, and `uv run mypy .` retain CI's whole-tree scope. |
Expand Down
12 changes: 11 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,19 @@ Use `pyproject.toml` as dependency/tool configuration authority rather than dupl
| `uv run pytest tests/<area>` | Scoped tests when assigned; use the repository markers and fixtures. |
| `python verify_docs_links.py` | Read-only repository Markdown path/anchor check; separate from `bin/check`. |
| `uv sync --all-extras` | **Writes:** development dependency installation, not verification. |
| `./scripts/setup-hooks.sh` | **Writes:** installs development pre-commit hooks. |
| `./scripts/setup-hooks.sh` | **Writes:** installs the development pre-commit hook; the installed hook runs the gate (`bin/check`) and propagates its exit status. |
| `uv run claudetm --help` | CLI smoke check; `doctor` and `status` may fail without credentials/state and are tolerated probes in `bin/check`. |

### Where the gate's tools come from

CI installs the project with `uv pip install -e ".[all]"`, and that install path does not read
`uv.lock`: CI runs the newest release inside pyproject's dev-extra ranges — `ruff>=0.16.1,<0.17`
and `mypy>=2.4.1,<2.5`. Local `uv sync --all-extras` and `uv run` do read `uv.lock`, so they run
the locked ruff 0.16.1 and mypy 2.4.1. A green local `bin/check` is therefore evidence for the
locked versions only; it is not proof that CI is green.

`requirements.txt` is a committed `uv pip compile` output of `pyproject.toml`, so it floats to the newest in-range releases (fastapi 0.149.0 against the lock's 0.139.2, pydantic 2.14.1 against 2.13.4); only claude-agent-sdk, ruff and mypy are held at `uv.lock`'s resolution, and it is not a gate input.

Follow the applicable skill before verification: `.claude/skills/verify-change/SKILL.md`,
`.claude/skills/docs-links/SKILL.md` or `.claude/skills/local-install/SKILL.md`.
Run the narrow reproducer first and the full gate once at the end; never weaken a test/type/lint guard
Expand Down
23 changes: 13 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,18 @@ Thank you for your interest in contributing to Claude Task Master! This document

```bash
# Run all tests
uv run pytest
uv run pytest tests/ --timeout=120

# Run specific test file
uv run pytest tests/core/test_agent.py
uv run pytest tests/core/test_agent_query.py --timeout=120

# Run with coverage report
uv run pytest --cov=claude_task_master --cov-report=html
uv run pytest tests/ --cov=claude_task_master --cov-report=html --timeout=120
```

pytest's addopts default to a 2-second timeout, so every command above
overrides it with `--timeout=120` — the value the gate (`bin/check`) uses.

### Code Quality

We use several tools to maintain code quality:
Expand All @@ -52,16 +55,16 @@ We use several tools to maintain code quality:
# Linting
uv run ruff check .

# Formatting
uv run ruff format .
# Formatting (check only — it never rewrites files)
uv run ruff format --check .

# Type checking
uv run mypy src/
# Type checking (the whole tree: src, tests and scripts)
uv run mypy .
```

Run all checks before submitting a PR:
Run all checks before submitting a PR — this is the lint, type-check and test step of the gate; `bin/check` also runs pytest with coverage and two workers, builds the package and runs the CLI smoke probes:
```bash
uv run ruff check . && uv run ruff format --check . && uv run mypy src/ && uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run mypy . && uv run pytest tests/ --timeout=120
```

### Code Style Guidelines
Expand Down Expand Up @@ -104,7 +107,7 @@ Types:

3. **Run all checks**:
```bash
uv run ruff check . && uv run ruff format . && uv run mypy src/ && uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run mypy . && uv run pytest tests/ --timeout=120
```

4. **Push and create PR**:
Expand Down
36 changes: 12 additions & 24 deletions scripts/hooks/pre-commit
Original file line number Diff line number Diff line change
@@ -1,29 +1,17 @@
#!/usr/bin/env bash
# Pre-commit hook to run lint and fix issues automatically
# Pre-commit gate — runs the SAME `bin/check` CI runs, so a commit that would
# fail CI fails here first.
# Installed by: scripts/setup-hooks.sh
#
# This hook auto-fixes lint/format issues without failing the commit.
# It silently fixes what it can and lets the commit proceed.
# The gate decides: the hook neither repairs the tree behind the committer's
# back nor reports success when the gate failed. The gate's exit status
# becomes the hook's, so a red gate blocks the commit.

# Get the staged Python files
STAGED_PY_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$' || true)
set -euo pipefail

if [ -z "$STAGED_PY_FILES" ]; then
exit 0
fi

# Run ruff check with fix on staged files (ignore errors)
uv run ruff check --fix $STAGED_PY_FILES 2>/dev/null || true

# Run ruff format on staged files (ignore errors)
uv run ruff format $STAGED_PY_FILES 2>/dev/null || true

# Re-add the fixed files to staging
for file in $STAGED_PY_FILES; do
if [ -f "$file" ]; then
git add "$file"
fi
done

# Always succeed - let the commit proceed
exit 0
repo_root="$(git rev-parse --show-toplevel)" || {
echo "pre-commit: cannot locate the repository root" >&2
exit 1
}
cd "$repo_root"
exec "$repo_root/bin/check"
5 changes: 3 additions & 2 deletions scripts/setup-hooks.sh
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,10 @@ mkdir -p "$HOOKS_DIR"
if [ -f "$SOURCE_HOOKS_DIR/pre-commit" ]; then
cp "$SOURCE_HOOKS_DIR/pre-commit" "$HOOKS_DIR/pre-commit"
chmod +x "$HOOKS_DIR/pre-commit"
echo " Installed: pre-commit (runs lint and fixes issues)"
echo " Installed: pre-commit (runs the full gate: bin/check)"
fi

echo ""
echo "Git hooks installed successfully!"
echo "The pre-commit hook will automatically run lint and fix issues on staged Python files."
echo "The pre-commit hook runs the full gate (bin/check) and blocks the commit when it fails."
echo "It runs the same gate as .githooks/pre-commit (git config core.hooksPath .githooks)."
167 changes: 167 additions & 0 deletions tests/test_gate_documentation.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,167 @@
"""Guard: the gate documentation must state where the gate's tools come from.

CI installs the project with `uv pip install -e ".[all]"`, an install path that does
not read `uv.lock`, so CI resolves the newest ruff and mypy release inside
pyproject's dev-extra ranges while a local `uv sync`/`uv run` resolves the versions
`uv.lock` pins. A green local gate is therefore not evidence about CI, and the docs
have to say so. This guard reads committed files only and derives its expectations
from pyproject.toml and uv.lock, so a bumped range or a re-locked version fails the
test until the documentation is updated.
"""

from __future__ import annotations

import re
import tomllib
from pathlib import Path

import pytest
from packaging.requirements import InvalidRequirement, Requirement
from packaging.specifiers import SpecifierSet

_ROOT = Path(__file__).resolve().parents[1]
_TOOLS = ("ruff", "mypy")

_CLAUDE_MD = _ROOT / "CLAUDE.md"
_SKILL_MD = _ROOT / ".claude/skills/verify-change/SKILL.md"
_CONTRIBUTING_MD = _ROOT / "CONTRIBUTING.md"

_CI_INSTALL = 'uv pip install -e ".[all]"'

# A version specifier is built from these characters; the scan for the range a doc
# attaches to a tool name stops at the first character outside the set.
_SPECIFIER_CHARS = set("<>=!~,.*0123456789")

# Each doc and the caveat it keeps about a local pass, quoted verbatim from that doc.
_DOC_CAVEATS = [
(_CLAUDE_MD, "not proof that CI is green"),
(_SKILL_MD, "not a guarantee that CI will pass"),
]


def _squash(text: str) -> str:
"""Drop every whitespace character: a doc may wrap one phrase over lines."""
return "".join(text.split())


def _declared(tool: str) -> Requirement:
"""The single requirement pyproject's dev extra declares for ``tool``."""
project = tomllib.loads((_ROOT / "pyproject.toml").read_text())["project"]
dev = project["optional-dependencies"]["dev"]
matches = [r for r in map(Requirement, dev) if r.name == tool]
assert len(matches) == 1, f"Declare {tool} in the dev extra exactly once"
return matches[0]


def _locked_version(tool: str) -> str:
"""The version uv.lock resolves for ``tool``."""
lock = tomllib.loads((_ROOT / "uv.lock").read_text())
resolutions = [p for p in lock["package"] if p["name"] == tool]
assert len(resolutions) == 1, f"uv.lock must resolve {tool} exactly once"
return str(resolutions[0]["version"])


def _states_range(text: str, tool: str, expected: SpecifierSet) -> bool:
"""Whether ``text`` states ``tool`` with a specifier set equal to ``expected``."""
squashed = _squash(text)
for match in re.finditer(re.escape(tool), squashed):
tail = squashed[match.end() :]
end = 0
while end < len(tail) and tail[end] in _SPECIFIER_CHARS:
end += 1
candidate = tail[:end]
if not candidate:
continue
try:
parsed = Requirement(f"{tool}{candidate}")
except InvalidRequirement:
continue
if parsed.specifier == expected:
return True
return False


def _has_line_with(text: str, *needles: str) -> bool:
"""Whether one line of ``text`` holds every needle once whitespace is dropped."""
for line in text.splitlines():
squashed = _squash(line)
if all(_squash(needle) in squashed for needle in needles):
return True
return False


@pytest.mark.parametrize("tool", _TOOLS)
@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name)
def test_doc_names_the_declared_range(tool: str, doc: Path) -> None:
"""The doc must state the range pyproject declares, not a stale copy of it."""
declared = _declared(tool)
assert _states_range(doc.read_text(), tool, declared.specifier), (
f"{doc.name} must state the {tool} range pyproject declares: {declared}"
)


@pytest.mark.parametrize("tool", _TOOLS)
@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name)
def test_doc_names_the_locked_version(tool: str, doc: Path) -> None:
"""The doc must state the version uv.lock pins, next to the tool name."""
version = _locked_version(tool)
assert f"{tool}{version}" in _squash(doc.read_text()), (
f"{doc.name} must state that {tool} {version} is the version uv.lock pins"
)


@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name)
def test_doc_names_the_ci_install_source(doc: Path) -> None:
"""The doc must name CI's install command and the lock it bypasses."""
text = doc.read_text()
assert _squash(_CI_INSTALL) in _squash(text), (
f"{doc.name} must name CI's install command {_CI_INSTALL}"
)
assert "uv.lock" in _squash(text), f"{doc.name} must name uv.lock"


@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name)
def test_doc_says_requirements_txt_is_not_a_gate_input(doc: Path) -> None:
"""The compiled artifact must be declared out of the gate's way."""
assert _has_line_with(doc.read_text(), "requirements.txt", "not a gate input"), (
f"{doc.name} must have a line stating requirements.txt is not a gate input"
)


@pytest.mark.parametrize(("doc", "caveat"), _DOC_CAVEATS, ids=["claude", "skill"])
def test_doc_keeps_the_local_pass_caveat(doc: Path, caveat: str) -> None:
"""A local pass is not evidence about CI; the doc has to say so."""
assert _squash(caveat) in _squash(doc.read_text()), (
f"{doc.name} must keep the caveat '{caveat}'"
)


@pytest.mark.parametrize("doc", [_CLAUDE_MD, _SKILL_MD], ids=lambda path: path.name)
def test_doc_states_the_hook_runs_the_gate(doc: Path) -> None:
"""The installed pre-commit hook runs the gate; the doc must say so."""
assert _has_line_with(doc.read_text(), "setup-hooks.sh", "bin/check"), (
f"{doc.name} must state that the hook installed by scripts/setup-hooks.sh runs bin/check"
)


def test_contributing_prescribes_the_gate_scope() -> None:
"""CONTRIBUTING.md must prescribe the checks the gate runs, not narrower ones."""
squashed = _squash(_CONTRIBUTING_MD.read_text())
assert _squash("uv run mypy .") in squashed, "CONTRIBUTING.md must prescribe `uv run mypy .`"
assert _squash("mypy src/") not in squashed, "CONTRIBUTING.md must not narrow mypy to src/"
assert _squash("uv run ruff format --check .") in squashed, (
"CONTRIBUTING.md must prescribe `uv run ruff format --check .`"
)
assert _squash("uv run ruff format .") not in squashed, (
"CONTRIBUTING.md must not prescribe the rewriting formatter"
)


def test_contributing_test_commands_use_the_gate_timeout() -> None:
"""Every prescribed test command must carry the gate's pytest timeout."""
lines = [line for line in _CONTRIBUTING_MD.read_text().splitlines() if "uv run pytest" in line]
assert lines, "CONTRIBUTING.md must prescribe the test command"
for line in lines:
assert "--timeout=120" in line, (
f"CONTRIBUTING.md test command lacks the gate's --timeout=120: {line.strip()}"
)
Loading
Loading