Skip to content

Document scripts/install-hooks.sh prominently in install.md #52

Description

@zzallirog

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsDocumentation / translationarea:securityPrivacy / outbound boundary / auditcommunity-invitationMaintainer-drafted, architecture pre-set, contributor implementspriority:5xx5 better, not parity — high-leverage compounding actionssize:SSmall — under a day

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions