Hooks and safety

Git hooks

Hooks install automatically on pnpm install. Manage them with:

pnpm hooks:status
pnpm hooks:disable-all

Bypass a single commit with git commit --no-verify. Set GIT_HOOKS=0 to skip hook setup entirely (CI/Docker).

Pre-commit: lint-staged

The pre-commit hook runs lint-staged over staged files only. JS and Markdown are linted with oxlint (pnpm lint) and formatted with oxfmt (pnpm format; pnpm format:check to verify). Config: .oxlintrc.json, .oxfmtrc.json.

Adoption is incremental: the pre-commit hook runs lint-staged over staged files only, and CI lints/format-checks only the files a PR changes. The repo has not yet been formatted wholesale; a one-time repo-wide oxfmt is a planned follow-up. Until then, do not run pnpm format across the whole tree in unrelated PRs.

Pre-push: skill version-bump enforcement

Changed skills must bump their version. Any change under a canonical skill directory (skills/<name>/ or plugins/*/skills/<name>/) requires that skill's SKILL.md version to increase. This is enforced by scripts/validate-skill-versions.mjs:

pnpm run validate:skill-versions -- --base-ref <ref>

It is wired into the PR-only skill-versions CI job and the local pre-push hook.

Pre-push: OAT tooling internal-flag enforcement

The OAT tooling skills mirrored under .agents/skills/** must stay hidden from npx skills discovery — the CLI honors metadata.internal: true in frontmatter to drop a skill from normal discovery (it reappears only under INSTALL_INTERNAL_SKILLS=1). Because those files are regenerated by oat tools update / oat sync, the flag is re-applied by an idempotent script and guarded by a gate rather than hand-edited:

• After refreshing tooling, re-stamp the flag: node scripts/apply-internal-flags.mjs, then oat sync. The script is idempotent and skips the symlinked session-observer mirror (a canonical standalone skill that must stay publicly discoverable).

• The detector scripts/validate-internal-flags.mjs:

  pnpm run validate:internal-flags

  is wired into the PR-only internal-flags CI job and the local pre-push hook, so a missing flag cannot merge to main. If it fails, run the apply script and re-commit the stamped files.

Do not add this flag to skills/session-observer or skills/export-session-transcript — those are the intended public standalone entries. See DR-260627 for the rationale.

Lint/format exclusions

Never lint/format generated, OAT-synced, or agent-instruction files: generated runtime outputs from scripts/build-generated.mjs, .agents/**, .claude/rules/**, .cursor/rules/**, and AGENTS.md / CLAUDE.md at every level.

Format exclusions must stay in sync across .oxfmtrc.json, .lintstagedrc.mjs, and the CI oxfmt --check step in .github/workflows/validate.yml; generated .mjs lint exclusions must also stay in sync across .oxlintrc.json, .lintstagedrc.mjs, and the CI oxlint step.

oxlint/oxfmt are dev tooling — they do not touch what shipped skills run.