What this is
scripts/install-hooks.sh installs a pre-commit hook that runs
scripts/leak-scan.sh before every commit, catching substrate files
(*.jsonl, *.npz, *.model) and personal paths before they enter the
git tree. This script exists but is invisible to users — it is mentioned only
in CLAUDE.md (maintainer-only reading). A user who commits directly from
the repo (rather than via the packaged CLI) has no prompt to install the hook.
This issue makes the script a visible, recommended step in the install docs.
Architectural answer (pre-set)
In docs/install.md, add a § Privacy hygiene (optional) section after
the system setup steps:
## Privacy hygiene (optional, recommended for contributors)
If you work with the repo checkout directly (cloned, not packaged), install
the pre-commit hook to prevent substrate files from accidentally entering
your git history:
bash scripts/install-hooks.sh
The hook runs `scripts/leak-scan.sh` before every commit and blocks any
commit that stages a `*.jsonl`, `*.npz`, `*.model`, or `*.pkl` file, or
a file containing a hardcoded home path. This is the same check that runs
in CI on every push.
If you use the packaged CLI (`pipx install weighted-compact`), you do not
need this hook — substrate files live in `$XDG_DATA_HOME/weighted-compact/`,
not in the repo tree.
In CONTRIBUTING.md, add a reference to this section under "Dev setup":
Install the pre-commit hook (see docs/install.md § Privacy hygiene) before
your first commit.
Open question for the contributor
Should the install.md section recommend the hook for all users (not just
contributors)? Recommended: no — only for users who clone the repo. The
packaged install path does not need it.
Where to start
docs/install.md — find the system setup section and add the new subsection.
scripts/install-hooks.sh — read it to verify what it installs and where.
CONTRIBUTING.md §"Dev setup" — add the one-line reference.
What NOT to do
- Do not make the hook installation part of the primary install path —
it remains opt-in for repo users.
- Do not add a
post-install script to pyproject.toml — that would
affect packaged users who don't need it.
- Do not change
scripts/install-hooks.sh itself.
Skill level
S — pure documentation addition, no code changes.
5× rationale
One accidentally committed pairs.jsonl in a contributor's fork would expose
raw conversation history in a public git history — a privacy incident that
cannot be fully remedied after the fact (git rewrite does not remove from
forks). The pre-commit hook is the prevention layer. Making it visible and
recommended in the install docs turns it from a maintainer nicety into a
user-facing privacy feature. The CI catches the same issue on arrival —
the hook is the "catch it before push" complement.
What this is
scripts/install-hooks.shinstalls a pre-commit hook that runsscripts/leak-scan.shbefore every commit, catching substrate files(
*.jsonl,*.npz,*.model) and personal paths before they enter thegit tree. This script exists but is invisible to users — it is mentioned only
in
CLAUDE.md(maintainer-only reading). A user who commits directly fromthe repo (rather than via the packaged CLI) has no prompt to install the hook.
This issue makes the script a visible, recommended step in the install docs.
Architectural answer (pre-set)
In
docs/install.md, add a§ Privacy hygiene (optional)section afterthe system setup steps:
In
CONTRIBUTING.md, add a reference to this section under "Dev setup":Open question for the contributor
Should the install.md section recommend the hook for all users (not just
contributors)? Recommended: no — only for users who clone the repo. The
packaged install path does not need it.
Where to start
docs/install.md— find the system setup section and add the new subsection.scripts/install-hooks.sh— read it to verify what it installs and where.CONTRIBUTING.md§"Dev setup" — add the one-line reference.What NOT to do
it remains opt-in for repo users.
post-installscript topyproject.toml— that wouldaffect packaged users who don't need it.
scripts/install-hooks.shitself.Skill level
S — pure documentation addition, no code changes.
5× rationale
One accidentally committed
pairs.jsonlin a contributor's fork would exposeraw conversation history in a public git history — a privacy incident that
cannot be fully remedied after the fact (git rewrite does not remove from
forks). The pre-commit hook is the prevention layer. Making it visible and
recommended in the install docs turns it from a maintainer nicety into a
user-facing privacy feature. The CI catches the same issue on arrival —
the hook is the "catch it before push" complement.