feat: implement native hooks runtime

README.md

@@ -1,5 +1,75 @@
 # pi-native-hooks
 
-Native Pi hooks runtime for shared analyzer results, contextual diagnostics, and verification completion gates.
+A native Pi extension that coordinates trusted personal policies after workspace mutations. It shares one ast-grep analysis snapshot across diagnostic policies and gates settlement until exact, current verification evidence exists or the agent records a reasoned waiver.
 
-The repository is seeded with an approved implementation plan. Runtime implementation has not started; begin with [`docs/implementation-plan.md`](docs/implementation-plan.md).
+## Requirements
+
+- Node.js 22.19 or newer
+- Pi 0.84.4 or compatible
+- ast-grep 0.45 or newer for diagnostics
+
+## Install
+
+Development installation is a separate, user-level mutation and is **not** performed by this repository's tests:
+
+```bash
+pi install /srv/data/code/jb-pi/pi-native-hooks
+```
+
+Then use:
+
+```text
+/hooks-init --dry-run
+/hooks-init --apply
+/hooks-doctor
+/reload
+```
+
+`--apply` displays every destination and asks for interactive confirmation. Existing files are preserved; newly created files are rolled back after a partial failure.
+
+## Trust model
+
+Files under `~/.config/pi-native-hooks/policies/*.ts` are trusted executable code. Importing them runs with Pi's filesystem, process, network, credentials, and outer sandbox authority. Structural validation is **not a sandbox**. The loader accepts only sorted direct-child `.ts` files and requires the config root, policies, ast-grep configuration, and rules to be owned by the current OS user, non-symlinked, regular files/directories, and not group/other writable.
+
+Personal policies use Node's erasable TypeScript subset: type-only syntax, interfaces, and `satisfies` work; enums, namespaces, parameter properties, JSX, and tsconfig transforms do not. Policies reload only with `/reload` or session replacement.
+
+## Diagnostics
+
+The starter policies flag TypeScript/TSX non-null assertions and dynamic imports. Both use `ast-grep:personal`, so one mutation wave runs one scan and fans the immutable snapshot to both policies. A justified exception uses the exact rule ID:
+
+```ts
+const plugin = await import(path); // ast-grep-ignore: typescript-no-dynamic-import-ts -- runtime-selected plugin
+```
+
+Analyzer failures are visible and never turn a successful mutation into a tool error. Unchanged findings are not repeatedly delivered.
+
+## Verification gate
+
+Starter project policies require these exact standalone commands from the matched Git project root:
+
+```text
+npm test
+npm run typecheck
+```
+
+Focused, combined, altered, wrong-directory, failed, aborted, concurrent, or stale commands do not count. A state-free session treats existing dirty files as its baseline; requirements arm only after an observed relevant mutation or restoration of armed branch state. At `agent_settled`, outstanding checks trigger another Pi turn.
+
+The agent may call `pi_hooks_waive_verification` with a non-empty reason. A waiver is auditable, revision-scoped, distinguishable from a pass, and expires after the next relevant mutation.
+
+Pi exposes foreground bash completion as `isError` rather than a numeric exit code. If a shell is externally signaled but Pi reports success, this extension cannot independently disprove completion. The settlement gate also cannot prevent a user or external client from closing Pi.
+
+## Commands
+
+- `/hooks-status` — policy digests and paths, trust/load failures, project identity, workspace revision, analyzer health, findings, verification revisions, evidence, waivers, and failures
+- `/hooks-init --dry-run` — preview external config writes
+- `/hooks-init --apply` — request authorization and initialize missing starter files
+- `/hooks-doctor` — validate policy loading and ast-grep availability
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+```
+
+Architecture and acceptance details are in [`docs/implementation-plan.md`](docs/implementation-plan.md). Event payload and project identity assumptions are pinned in [`docs/event-contract.md`](docs/event-contract.md).