Validate Before Commit

This skill enacts the Algorithms Before Tokens axiom from MANIFESTO.md: validation is encoded once as a deterministic gate and executed consistently, not re-checked interactively per session. The full guardrail sequence is governed by AGENTS.md § Guardrails. When this skill and those documents conflict, the primary documents take precedence.

1. Decision Table — Which Checks Apply

Run the checks corresponding to which file types were changed:

Pre-commit hook coverage — the hooks in .pre-commit-config.yaml run automatically on git commit (and fast-tests on git push) once installed with uv run pre-commit install. They cover every row in this table. If pre-commit is installed, manual checks are needed only for lychee dead links (network-only, no local equivalent).

When in doubt, run all checks. The full sequence takes under 60 seconds on a warm environment.

2. Full Check Sequence

2.1 Lint and Format

uv run ruff check scripts/ tests/
uv run ruff format --check scripts/ tests/

To auto-fix format violations (safe, no logic changes):

uv run ruff format scripts/ tests/

2.2 Fast Tests

uv run pytest tests/ -x -m "not slow and not integration" -q

The -x flag stops on the first failure. The marker filter skips network and slow tests — fast enough to run before every commit.

2.3 Agent File Compliance

Run this only when .github/agents/*.agent.md files were changed:

uv run python scripts/validate_agent_files.py --all

To check a single file:

uv run python scripts/validate_agent_files.py .github/agents/<file>.agent.md

2.4 Skills Compliance

Run this only when .github/skills/ files were changed:

uv run python scripts/validate_agent_files.py --skills

2.5 Research Doc Compliance

Run this only when docs/research/*.md files were changed:

uv run python scripts/validate_synthesis.py docs/research/<changed-file>.md

2.6 Value-Encoding Drift Check

Run this when .github/agents/*.agent.md files were changed:

uv run python scripts/detect_drift.py --agents-dir .github/agents/ --format summary --fail-below 0.33

A drift score below 0.33 means the agent file lacks sufficient MANIFESTO.md axiom references. Fix by adding explicit citations to Endogenous-First, Algorithms Before Tokens, or Local Compute-First in the agent body.

2.7 Push-Stage: Full Fast Tests

The fast-tests hook is configured as a push-stage hook and runs automatically on git push once pre-commit is installed. To run manually before pushing:

uv run pytest tests/ -x -m "not slow and not integration" -q

3. Pre-Commit Hooks

Pre-commit hooks automate ruff, validate-synthesis, and validate-agent-files on every git commit; fast-tests runs on every git push. Install both once per clone:

uv run pre-commit install
uv run pre-commit install --hook-type pre-push

After installation, hooks run automatically on git commit. You do not need to run the manual checks above for files covered by the hooks — but running them proactively surfaces issues earlier in the workflow.

Never use --no-verify to skip pre-commit hooks. Bypassing hooks is explicitly prohibited by AGENTS.md § Guardrails.

4. CI Gate — Wait for Green Before Review

After every git push:

gh run list --limit 3

Wait for the latest run to show a green ✓ status before requesting or re-requesting Copilot review. A push with failing CI is a broken PR — fix the failures before doing anything else.

Common CI failure modes:

Lychee (Dead Link Checks)

Lychee two-step rule: After any lychee fix commit, always wait for CI to complete before declaring lychee clean. CI runners receive intermittent 503s from high-traffic domains (e.g., theatlantic.com) that local lychee does not reproduce. These produce a second CI failure requiring a separate .lycheeignore entry and re-push. Lychee is clean only when CI is green, not when local check exits 0.

5. Commit Only After All Checks Pass — Orchestrator Terminal Operations

The Orchestrator performs commits via direct terminal operations after all checks pass. The full validation sequence in order:

# 1. Lint + format
uv run ruff check scripts/ tests/
uv run ruff format --check scripts/ tests/

# 2. Fast tests
uv run pytest tests/ -x -m "not slow and not integration" -q

# 3. Agent file compliance (if .github/agents/ changed)
uv run python scripts/validate_agent_files.py --all

# 4. Skills compliance (if .github/skills/ changed)
uv run python scripts/validate_agent_files.py --skills

# 5. Research doc compliance (if docs/research/ changed)
uv run python scripts/validate_synthesis.py docs/research/<changed-file>.md

# 6. Commit
git add <files>
git commit -m "<type>(<scope>): <description>"

# 7. Push and verify CI
git push
gh run list --limit 3

Guardrails

• Never commit with --no-verify — pre-commit hooks are not optional.
• Never push without waiting for CI before requesting review.
• Never skip the research doc validation step when docs/research/ files change.
• Do not interpret a zero exit from git push as CI passing — always check gh run list.

Script Usage Verification

Before invoking any script or tool for the first time in a session:

1. Run uv run python scripts/<script>.py --help or read its module docstring
2. Assert that all required input parameters are present and correctly typed
3. Confirm expected output format matches the consuming agent's expectations
4. Check known error modes — does the script exit non-zero on partial failure?

Encoding point: This step is governed by AGENTS.md § Guardrails — Verification-First rule, derived from orchestrator-autopilot-failure.md § Recommendation 3.