Install check: assert every hook entrypoint is registered for its event

[EdbertChan]

Summary

The install check tells people when their local agent setup does not match this project.

Some hook files were skipped. A folder name anywhere in the settings also counted as a match.

The check now reads all hook files. It matches each event and command with the local settings.

It also trusts skill folders made by the installer. It still reports hand-made folders that hide project skills.

Review Claim

Approve a check that finds each missing hook and accepts skill folders made by the installer.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

The verifier only reads repository declarations and local settings. It does not write files or install software.

Unreadable or invalid settings produce an unchecked result, not a pass.

Assumptions: The user has not confirmed this safety invariant in this session.

Slice Rationale

The verifier and its regression coverage form one review claim. The coverage proves the failure and success paths of the same read-only check.

Non-goals

• No installer behavior changes.
• No hook implementation changes.
• No changes to other installation checks or CI wiring.

Architecture

Before

graph TD
    A["One default hook declaration per folder"] --> B["Search the raw settings text for the folder name"]
    B --> C["Report missing folder names"]
    D["Installed skill directory"] --> E["Always report a shadow conflict"]

Loading

After

graph TD
    A["Every hook declaration file"] --> B["Parse event and command pairs"]
    C["Local settings"] --> D["Parse registered event and command pairs"]
    B --> E["Compare exact pairs"]
    D --> E
    E --> F["Report each missing registration"]
    G["Installed skill directory"] --> H["Check the generated marker"]
    H --> I["Accept generated directories or report hand-made conflicts"]

Loading

Test Plan

Test Plan

• python3 engine/skills/make-pr/scripts/preflight.py --base origin/main

  unit    engine-runtime: 1 file(s)
  neutral 1 file(s): tests/test_install_effective.py
  declare Review Unit: engine-runtime
  gates   none required for these paths
  ok      preflight passed
  

• python3 -m unittest discover -s tests -p 'test_install_effective*' -v: 22 tests passed.

• python3 scripts/check_no_new_comments.py --base origin/main: no new comments found.

• python3 -c "import ast; ast.parse(open('scripts/check_install_effective.py').read())": exited 0.

• bash scripts/scrub-handoff-artifacts.sh: reported scrub-handoff-artifacts-ok.

Revert Plan

Revert Plan

• Safe to revert? Yes. The change only affects a read-only verifier and its tests.
• Revert command: git revert <merge-commit-sha>
• Post-revert steps: None.
• Data migration? No.

---

Note

Low Risk
Changes only affect a read-only verification script and unit tests; no installer, hook runtime, or settings writes.

Overview
Tightens the read-only install verifier so hook drift is detected precisely and installer-created skill layouts are not false positives.

Hook registration no longer treats a hook folder name appearing anywhere in ~/.claude/settings.json as registered. It parses JSON from settings and from every engine/hooks/*/claude*.hook.json, then flags each declared event + command that is missing from settings. Unreadable or invalid settings yield UNCHECKED notes instead of a silent pass.

Skills: real directories under ~/.claude/skills/<name> are still drift unless they contain a .catstack-generated marker, in which case the checker skips them.

Tests add helpers for synthetic hook declarations and settings, cover wrong event, wrong command, and correct registration, plus generated vs hand-made skill directories.

^{Reviewed by Cursor Bugbot for commit 1c518bb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_6cf1de49-8f81-45ff-84ea-2dce1a02c9aa)

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[EdbertChan]

Mergify repair stopped: missing required check validate