Mechanical Enforcement

Mechanical Enforcement

Rules a reviewer would otherwise have to remember belong in a linter. This skill is the curated catalogue of rules, the linters that enforce them, and the rationale for each, so a new project is hardened without re-deriving the set.

A content skill, not a tool: rules and snippets. Wiring them into git hooks is the hk skill's job.

Principles

1. Mechanical over social. If a rule relies on a reviewer remembering it, it will drift. Encode it in a linter, a type, or a test - never in a convention.
2. Types first, lint second, tests third. Prefer strict TypeScript / Pydantic / clippy to a custom lint rule. Reach for a lint rule when the type system can't express it. Reach for a test only when neither can.
3. Architectural boundaries are linter rules. Layers (domain <- infra, UI <- schemas) are enforced with no-restricted-imports or a graph check when the rule is transitive, never trusted to vigilance.
4. Auto-fix where possible, gate where not. Formatters and whitespace fixers run with fix = true and re-stage. Correctness rules gate the commit.
5. Own the rule list where the rules are the point, take a preset where they are not. @commitlint/config-conventional for commits and next/core-web-vitals for Next are presets worth inheriting; the lint set that backs an idiom is a config this catalogue owns, because a preset that silences one of those rules does it silently. Override either only with a comment saying why.
6. The why lives with the rule. Every non-obvious override has an inline comment saying what would break if it were removed.

When to use this skill

• New project → pick from the table below, read that stack's reference, copy its drop-ins, wire with hk.
• Existing project → audit against the stack reference, add what is missing, ratchet what lands red.
• A bug just happened → "what rule would have caught this mechanically?" (Adding a new rule).
• Unfamiliar stack → the picks table.

Picks by stack

The table names the defaults. The Read column is where each pick is justified, its traps listed and its hk tier map kept - read it before configuring anything.

Framework single-file components (.astro / .vue / .svelte) have no row: the Rust JS linters misread their templates - see references/typescript.md (Framework single-file components).

Locale spell-checker caveat. A locale-rewriting spell hook (typos en-gb, aspell) auto-"fixes" US-spelled external identifiers inside string literals - CLI flags (--flavor), protocol names (authorization), CSS keywords (color, center), schema.org types, API fields - and silently breaks the build or the wire. Allow-list the class proactively (a fixed word list rots as the dictionary drifts) and re-check string literals after any auto-fixed commit. Wiring: hk [default.extend-words], hk/references/builtins-by-language.md.

Rules catalogue

Rules are organised by concern, not by linter: what it prevents, how to encode it, known exceptions. The routing table at the end says which reference owns which concern; only the two every repo has stay inline.

Secrets & CI hardening

Run zizmor and actionlint together - minimal overlap, both static. agent-ci executes a workflow locally in the real runner image: a dynamic complement, not a linter. Dependency supply-chain posture (quarantine keys and units, install-script blocking, osv-scanner, provenance, the Actions-cooldown bug) is the supply-chain-hardening skill's; this skill keeps the linter-shaped controls above and the config-drift-checker pattern.

Commit messages

// commitlint.config.js
export default { extends: ["@commitlint/config-conventional"] };

Wire via hk's commit-msg hook (see references/hk-steps.pkl). Nothing else to configure.

Composition with the hk skill

This skill gives you what to enforce; the hk skill gives you how to wire it. The generic ladder - each stack reference's Picks section maps its tools onto it:

tier 1 (format/fix)          → trailing-whitespace, newlines, typos, the stack formatter (fix = true, re-staged)
tier 2 (lint/gate)           → the stack linter incl. boundary and purity rules, gitleaks, yamllint, check-merge-conflict, zizmor --offline + actionlint (glob .github/workflows/*.{yml,yaml}, action.yml)
tier 3 (typecheck)           → the stack type checker
tier 4 (deps/dead code/test) → dependency and dead-code gates, the test runner scoped to changed paths by glob
CI / pre-push                → baseline-diff contract gates (buf breaking / oasdiff / cargo-semver-checks / api-extractor), squawk on migrations/**/*.sql, publish gates, audits
commit-msg                   → commitlint

Baseline-diff gates run at pre-push / CI, not pre-commit: they need the base ref. Use fix = true + stash = "git" on pre-commit so tier 1 auto-fixes and re-stages. Worked example: references/hk-steps.pkl.

Adding a new rule

When a bug escapes to review or production, the retro question is: what rule would have caught this mechanically?

1. Identify the smallest AST pattern, import, or type flag that expresses the rule.
2. Pick the linter that already owns that concern (the picks table).
3. Add it, with an inline comment explaining the failure mode it prevents.
4. Record it with the same rationale in the matching references/ stack file (inline above only for a cross-stack concern), and as a drop-in if it is a new type of rule.

Ratcheting a gate onto non-conforming code

A hard threshold (complexity cap, coverage floor, a new no-restricted-* or graph rule) fails the whole build the day it lands on a codebase that already violates it - so it gets reverted, or slackened to a ceiling that governs nothing. Ratchet instead (Ford/Parsons): record today's violations as a committed baseline, fail only new ones, shrink the baseline deliberately, and never refresh it in CI. The vehicle per tool and the traps in each: references/ratcheting.md.

Complexity gates are the archetype. If the number you want produces more than a couple of dozen violations, it is a refactoring backlog, not a gate - carry it as CI reporting until the backlog shrinks. A number chosen to make today's worst file pass is not a gate.

References

External: hk (git hook manager), Ultracite (an optional React/Next preset over the oxc stack, with the traps references/typescript.md lists).