Should Maka install local validation hooks by default?

[Phoenix500526]

Context

PR #4132 proposes installing Husky hooks during normal root dependency setup. The goal is to run existing repository checks before a branch is pushed, especially when an agent-assisted change violates a repository assumption.

Today those failures often appear only in CI, which adds an avoidable edit, push, and wait cycle.

Proposed behavior

A regular npm install or npm ci would install two hooks:

• pre-commit checks staged changes with Biome, checks ASF headers on new files, runs the Runtime Host protocol epoch guard, and runs git diff --cached --check.
• commit-msg validates Conventional Commit messages with commitlint.

The hooks reuse existing repository checks. CI remains the authority.

Local control and recovery

This changes every local commit, including intermediate commits.

• Skip the hooks for one commit with git commit --no-verify.
• Disable Husky for a command or environment with HUSKY=0.
• npm ci --omit=dev does not install Husky. The prepare script skips hook setup when Husky is absent.
• If hooks already exist but development dependencies are later omitted, the hooks fail clearly instead of running cached or global tools. Run a normal npm install to restore the local tools, or bypass the hooks intentionally.

Questions

1. Should these hooks be installed by default for contributors?
2. Should commit-message validation apply to every local commit, or only to PR titles and merged commits?
3. Would an opt-in setup be better than automatic installation?

Implementation: #4132

[Phoenix500526]

@Astro-Han

[Astro-Han]

Thanks for splitting this out — and for the recovery section, which is the part I'd have asked about first.

The pre-commit half I think is worth having. Biome, ASF headers, and the protocol epoch guard are exactly the things that get missed and then cost a push-and-wait cycle to discover. Catching them locally is a real saving, and the checks are ones we already own.

Whether it's installed by default shouldn't be decided by whoever happens to be in this thread. It changes every contributor's local environment, including people who have never hit the problem, and the ones who'd feel it most are the ones not reading this discussion.

So let's settle that one by vote here. Please reply with one of:

• +1 — install the hooks by default during normal dependency setup, as feat(ci): add fast local validation hooks #4132 proposes.
• -1 — don't install anything automatically; ship a npm run check:local that runs the same checks, and let people opt in.

PPMC votes are binding; everyone else, please vote anyway — this affects contributors more than it affects committers. I'll leave it open at least 72 hours, longer if discussion is still active, and summarize the outcome here.

The commit-msg half I don't think earns its place, independently of that vote. commitlint here is just @commitlint/config-conventional, so it validates <type>(<scope>): <summary> on every local commit — but Conventional Commits is a rule about branches and PR titles in our contributing guide, and we squash-merge, so the title is what becomes the commit on main. Enforcing it on intermediate commits polices something that never reaches history.

If we want a commit-message hook, the rule worth enforcing is the one CONTRIBUTING actually places on individual commits: the Generated-by: <tool> trailer when AI authors a material part of a change, kept through squash or amend. That is easy to forget, it does reach main, and nothing checks it today. Either drop commit-msg, or point it at that.

简体中文

感谢你把这件事单独拿出来讨论——尤其是那一节「本地控制与恢复」，那正是我首先会问的部分。

pre-commit 这一半我认为值得做。 Biome、ASF 头、协议 epoch guard，恰恰是最容易漏、又要等一轮 push 才能发现的东西。在本地拦住确实省事，而且这些检查本来就是我们自己的。

但「是否默认安装」不该由恰好在这个帖子里的人决定。 它会改变每一位贡献者的本地环境，包括那些从未遇到过这个问题的人；而受影响最大的，恰恰是不会读到这个讨论的人。

所以这一条我们在这里投票决定。请回复以下之一：

• +1 —— 按 feat(ci): add fast local validation hooks #4132 的提议，在正常安装依赖时默认装上 hooks。
• -1 —— 不自动安装任何东西；提供一个执行同样检查的 npm run check:local，由各人自行选择启用。

PPMC 成员的投票具有约束力；其他人也请参与投票——这件事对贡献者的影响大于对 committer 的影响。我会至少留 72 小时，若讨论仍在进行则延长，并在此汇总结果。

commit-msg 这一半，无论投票结果如何，我都认为不值得。 这里的 commitlint 就是 @commitlint/config-conventional，它在每一次本地提交上校验 <type>(<scope>): <summary>——但在我们的贡献指南里，Conventional Commits 约束的是分支名和 PR 标题，而且我们是 squash merge，最终落到 main 上的是标题。在中间提交上强制它，管的是永远不会进入历史的东西。

如果我们确实想要一个 commit-message hook，值得强制的是 CONTRIBUTING 真正施加在单个 commit 上的那条规范：当 AI 撰写了改动的实质部分时，加上 Generated-by: <tool> trailer，并在 squash 或 amend 后保留。这条容易被忘记、确实会进入 main，而且今天没有任何检查。要么去掉 commit-msg，要么把它指向这条。

(Drafted with AI assistance; I verified the hook scripts, the commitlint config, and the CONTRIBUTING rules myself.)

[Phoenix500526]

+1

[Phoenix500526]

@Astro-Han I've already removed the commit-msg half.