pi-native-hooks/skills/native-hook-authoring/references/contracts.md

Policy contracts

The authoritative declarations are exported by pi-native-hooks/policy from src/policy.ts. Do not copy them into personal config.

A diagnostic policy declares kind, a unique id, analyzer keys, appliesTo, and a pure evaluate. evaluate receives readonly normalized snapshots and a process-free policy context. Filter findings by exact rule ID and return bounded guidance plus the supported suppression form.

A verification policy declares a project matcher and exact requirements. Each requirement owns an exact command, cwd: "project-root", and a pure affects(path) predicate. Do not infer scripts or accept command variants.

Use:

import type { DiagnosticPolicy } from "pi-native-hooks/policy";
export default { /* ... */ } satisfies DiagnosticPolicy;

No runtime import is needed. Enums, namespaces, parameter properties, JSX, and tsconfig transforms are unsupported in personal modules.