Poly Hooks¶

AI-Rulez publishes a reusable Poly hook catalog in poly-hooks.toml. Consumer repositories declare Git or local sources in their existing poly.toml and select the hooks they need. Consumers do not create another poly-hooks.toml.

The catalog exists since AI-Rulez 4.9.0 and needs Poly 0.14.0 or later. The catalog revision pins hook definitions. The system execution path uses the installed ai-rulez executable; provision the reviewed CLI version separately in local setup and CI.

Add AI-Rulez to a repository¶

Add a Git source to poly.toml:

[[hooks.sources]]
id = "ai-rulez"
git = "https://github.com/Goldziher/ai-rulez.git"
revision = "v5.6.3"
hooks = ["ai-rulez-validate"]

Use ai-rulez-validate as the non-mutating default. Plugin-producing repositories should also verify their generated bundles:

hooks = ["ai-rulez-validate", "ai-rulez-check", "ai-rulez-plugin-verify"]

Every Git source requires an explicit revision and a nonempty hook selection. Unknown hook IDs are rejected. Hooks added to a future version of the producer catalog never activate unless you select them.

Resolve the revision, commit the lock, and install the Git shims:

poly hooks update
git add poly.toml poly-hooks.lock
poly hooks install

Normal hook runs use the locked commit and never move Git references. Run poly hooks update explicitly after changing revision or when intentionally refreshing a branch reference.

Available hooks¶

Hook	Command arguments	Purpose
`ai-rulez-validate`	`validate --no-local`	Validate the root configuration and content
`ai-rulez-check`	`generate --check --no-local`	Check generated governance output drift
`ai-rulez-generate`	`generate --no-local`	Regenerate the root project
`ai-rulez-recursive`	`generate --recursive --no-local`	Regenerate every project in a repository
`ai-rulez-plugin-generate`	`generate --recursive --plugin --if-configured`	Regenerate plugin producers and marketplaces
`ai-rulez-plugin-verify`	`verify --recursive --plugin --if-configured`	Verify plugin provenance without writing files

Source-scoped hooks trigger for root or nested .ai-rulez/ changes. The read-only governance check triggers on every tracked change so presets, custom output paths and output deletions cannot bypass drift checking; plugin verification triggers on generated plugin and marketplace files so a change to generated bytes alone cannot bypass verification. Both read-only checks always run because Poly excludes deleted files from its staged file list; a deletion-only commit must still check that the generated outputs exist.

Machine-local configuration in hooks¶

The generate hooks pass --no-local, so they render the shared view a teammate or CI sees and ignore the developer's gitignored config.local.* overlay and .ai-rulez/local/ content. Machine-local outputs are left in place; run ai-rulez generate without the flag to refresh them. ai-rulez-plugin-verify already checks the shared view, and plugin generation ignores the overlay. Do not add --allow-local-drift to hooks. See Local Configuration.

Choose an execution path¶

Hooks use the installed ai-rulez executable. Select the system channel in the gitignored poly.local.toml and install the reviewed CLI version before installing hooks:

[hook_preferences]
channels = ["system"]

The hook catalog deliberately has no on-demand package-manager fallback: its pinned Git revision must not quietly execute a different released CLI. Poly runs the system channel only after command -v ai-rulez succeeds.

Poly does not silently choose a channel when external hook sources are configured. A missing preference list or a source with no eligible path is an error. If the selected AI-Rulez command fails, the hook fails without falling through to another path.

Use a local source¶

For hook development, replace git and revision with path:

[[hooks.sources]]
id = "ai-rulez"
path = "../ai-rulez"
hooks = ["ai-rulez-validate"]

Local paths may be repository-relative, parent-relative, or absolute. Poly canonicalizes the path, loads the producer catalog on every run, and does not create a lock entry for it. A source must specify exactly one of git or path.

Producer catalog¶

Only the producer repository owns poly-hooks.toml. A catalog contains one or more hooks, and every hook contains at least one guarded execution path:

version = 1

[[hooks]]
id = "ai-rulez-validate"
stages = ["pre-commit"]
args = ["validate", "--no-local"]
files = [".ai-rulez/**", "**/.ai-rulez/**"]
workspace = true
pass_filenames = false

[[hooks.paths]]
channel = "system"
check = "command -v ai-rulez"
run = "ai-rulez"

Poly appends the hook's args to the selected path's run command. install is optional because paths such as system use an already-installed executable. Workspace hooks run from the consumer repository root. Duplicate hook IDs, duplicate channels within a hook, empty paths, and unsupported catalog versions are errors.

Recursive plugin checks¶

Plugin authoring means a [plugin] block or a [marketplace] block with members. Consumer-only [[plugins]] and [[marketplaces]] declarations do not count.

Recursive plugin commands treat a marketplace root atomically: the root renders or verifies its member plugins and aggregate indexes, while member configs are excluded from duplicate concurrent work. Standalone plugin producers are processed normally. --if-configured only turns the absence of an authoring config into success; real generation and verification errors still fail the hook.

Warning

Hook catalogs execute commands with your user permissions. Review source and lock changes before running or installing hooks.

Root validation and drift checks do not recursively treat plugin-authoring configs as governance projects. Plugin authors intentionally produce bundles rather than per-repository assistant files; plugin verification validates their generated bundles recursively. Run root governance hooks once per canonical repository so peer worktrees and unrelated nested repositories are not checked.