ai-push-hooks 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-09-12
+
+This is a beta patch release. Python and npm both use `0.3.2`, the canonical
+Git tag is `v0.3.2`, npm uses the `beta` dist-tag, and GitHub marks the release
+as a prerelease. PyPI does not provide a separate beta channel, so Python users
+must select the exact `0.3.2` version.
+
+### Changed
+
+- Added a pinned Ruff 0.13.3 formatting policy for Python sources, tests, and scripts.
+- Updated the default OpenCode model and README positioning to
+  `openai/gpt-5.6-luna`.
+- Clarified that built-in mutating steps are serialized, while trusted custom
+  command runners, including project-access `ask` commands, are not enforced
+  read-only.
+- Removed the unused secondary shell launcher in favor of the canonical Python
+  console script and npm wrapper.
+
+### Fixed
+
+- Review initial publication of the configured base branch against the empty
+  tree, while retaining configured-base comparison for new feature branches.
+- Persist bounded diffs as valid UTF-8, truncating at character boundaries and
+  representing malformed bytes with replacement characters within the budget.
+- Hardened pull-request creation by validating generated payload types,
+  reconciling failed `gh` calls against GitHub, and keeping remote credentials
+  out of diagnostics.
+- Bounded config, prompt, and callback source reads and rejected unsafe config
+  file types.
+- Rejected duplicate workflow identifiers and simplified workflow step result
+  handling.
+- Made source distributions complete and added validation of their unpacked
+  test suite and wheel builds with the minimum supported setuptools 77 backend.
+- Standardized development and release validation on the isolated project
+  `.[dev]` extra instead of repeating tool lists.
+- Restored the PyPI release job's checkout permission and pinned the OpenCode
+  contract test's base container image.
+
+### Documentation
+
+- Added an agent setup skill, CI/npm beta badges, and a reproducible,
+  deterministic review/fail/fix/commit/pass demo, explicitly not live AI footage.
+- Explained the manual-commit assertion and why applied edits are not part of
+  the commit already being pushed.
+- Included the configuration guide in the npm package and removed its link to
+  the local-only runner verification report.
+
 ## [0.3.1] - 2026-09-10
 
 ### Changed
@@ -149,7 +196,8 @@ the exact `0.2.0` version rather than a PyPI beta channel.
 - Preserved Git porcelain paths and protected pre-existing dirty allowlisted files during apply steps.
 - Clarified module-local artifact references and standardized the repository hook integration.
 
-[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.2.0...v0.2.1

package/README.md

@@ -1,134 +1,145 @@
 # ai-push-hooks
 
-**Modular AI checks before `git push`.**
+[![CI](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml) [![npm beta](https://img.shields.io/npm/v/ai-push-hooks/beta?label=npm%20beta)](https://www.npmjs.com/package/ai-push-hooks/v/beta)
 
-Use **OpenCode, Codex, or Claude Code** to review outgoing changes, check that code and docs agree, and apply scoped fixes. Combine AI reasoning with your own scripts, tests, and rules in a repo-local Git hook.
+**Agentic linting for the rules your coding agent forgot.**
 
-- **Check alignment:** compare changes with documentation, requirements, or task state.
-- **Ask or apply:** get findings without edits, or let AI update explicitly allowed files.
-- **Verify before pushing:** run deterministic checks and block when your rules fail.
-- **Build your workflow:** choose modules, prompts, and runners per step.
+`AGENTS.md` tells an agent how to work. **ai-push-hooks checks whether it followed through.** Think of it as the inverse of `AGENTS.md`: a second pass over outgoing changes before `git push`, catching guidelines the agent forgot or neglected.
+
+Use **OpenCode, Codex, or Claude Code** to check rules that need judgment, not just a regex. Report violations, apply scoped fixes, and block pushes with explicit checks. It's a hedge against missed instructions, not a guarantee that AI catches everything.
+
+## Rules Worth Checking
+
+| Your rule | What the check looks for |
+| --- | --- |
+| No empty marketing speak. | Vague claims and filler in changed pages. |
+| Use our typed API client. | Components making direct backend requests. |
+| Test behavior, including failures. | Changed behavior without meaningful test coverage. |
+| Keep migrations backward-compatible. | Destructive changes that break a rolling deployment. |
+
+Write your own rules in prompts or supply a rules file as context. These are examples of checks you configure, not built-in guarantees.
+
+## Why Now?
+
+With lower-cost models such as GPT 5.6 Luna, GLM 5.3 Flash, Muse Spark 1.3, and Gemini Flash, running several focused agentic checks on each push can be practical, rather than reserving AI review for special occasions. Keep context narrow and measure your workflow's cost and latency. GPT 5.6 Luna is the default.
 
 ## Quick Start
 
+Install the [ai-push-hooks skill](https://github.com/shanebishop1/ai-push-hooks/blob/main/skills/ai-push-hooks/SKILL.md), tell your agent what intelligent checks you want before pushes, and let it set up the modules for you.
+
 ```bash
 npm install --save-dev ai-push-hooks@beta
-npx --no-install ai-push-hooks init --template minimal-docs
+npx --no-install ai-push-hooks init
 npx --no-install ai-push-hooks install
 ```
 
-Choose your [runner and model](#choose-your-ai) in `ai-push-hooks.toml`, then push normally. The starter checks docs, applies fixes, and stops for review if anything changed.
+Install and authenticate your chosen AI CLI. The current `init` starter checks documentation; replace its configuration with the rules-checking example below to check `AGENTS.md` instead. Then push normally.
 
 [Other installation options](docs/configuration.md#installation) | [Existing hook managers](docs/configuration.md#hook-managers)
 
-## Modular By Design
+## Deterministic Demo
 
-A workflow is a list of modules. Each module combines the steps it needs:
+![Review, fail, fix, commit, pass: deterministic demo](https://raw.githubusercontent.com/shanebishop1/ai-push-hooks/main/docs/demo/review-fix.gif)
 
-| Step | Purpose |
-| --- | --- |
-| `collect` | Gather the outgoing diff and relevant context. |
-| `ask` | Ask AI for plain text or schema-validated JSON. |
-| `apply` | Let AI edit a temporary workspace; copy back only allowlisted changes. |
-| `exec` | Run a command, Python callback, or built-in action. |
-| `assert` | Enforce a rule and block the push if it fails. |
+This generated GIF summarizes actual hook results from a disposable repository with a local deterministic command runner; it is not a live screen recording or live AI. It makes no provider calls, remote pushes, or Beads changes. Regenerate it with `uv run --no-project --with pillow==11.3.0 python docs/demo/generate.py`.
 
-Use a review-only module, an apply-only module, or a full collect/ask/apply/verify flow. Add your existing lint and test commands alongside AI checks. No AI runner is needed for deterministic-only workflows.
+## Example: Check Your Rules
 
-## Choose Your AI
+This workflow supplies the outgoing diff and your root `AGENTS.md` explicitly, asks for violations, and blocks if any are reported. It does not rely on the runner automatically loading agent instructions.
 
-Set the default runner in `ai-push-hooks.toml`. Change it to `codex` or `claude` to switch tools:
+In `checks/hooks.py`:
 
-```toml
-[llm]
-runner = "opencode"
+```python
+import json
 
-[runners.opencode]
-type = "opencode"
-model = "provider/model-id" # Replace with an available OpenCode model.
-project_access = "artifacts"
+from ai_push_hooks.plugins import CollectorResult, PluginContext
 
-[runners.codex]
-type = "codex"
 
-[runners.claude]
-type = "claude"
-```
+def collect_rules(context: PluginContext) -> CollectorResult:
+    return CollectorResult(artifacts={
+        "push.diff": context.push.diff_text,
+        "rules.txt": (context.repo_root / "AGENTS.md").read_text(encoding="utf-8"),
+    })
 
-Each `ask` or `apply` step can override the default with, for example, `runner = "claude"`. You can review with one tool and apply with another.
 
-OpenCode defaults to collected artifacts only. Set `project_access = "project"` for repository reads; Codex and Claude default to project access. Each runner uses its own authentication and model identifiers.
+def assert_rules(context: PluginContext) -> dict:
+    issues = json.loads(context.inputs["review/issues.json"].read_text(encoding="utf-8"))
+    return {"ok": issues == [], "message": "Review findings in review/issues.json."}
+```
 
-Other tools, including Pi, can use a [custom command runner](docs/configuration.md#custom-runners).
+In `ai-push-hooks.toml`:
 
-## Example: Docs Alignment
+```toml
+[llm]
+runner = "opencode"
 
-This workflow asks AI to find documentation drift, applies narrow fixes, and requires human review when files change. Use it with the runner settings above:
+[runners.opencode]
+type = "opencode"
+model = "openai/gpt-5.6-luna"
+project_access = "project"
 
-```toml
 [workflow]
-modules = ["docs"]
+modules = ["rules"]
 
-[[modules.docs.steps]]
+[[modules.rules.steps]]
 id = "collect"
 type = "collect"
-collector = "docs_context"
+python = "checks/hooks.py:collect_rules"
 
-[[modules.docs.steps]]
+[[modules.rules.steps]]
 id = "review"
 type = "ask"
-prompt = "Check that the docs match the outgoing code changes. Return a JSON array of factual issues with file and description fields, or [] if aligned."
-inputs = ["collect/push.diff", "collect/docs-context.txt"]
+prompt = "Check the outgoing diff against rules.txt. Inspect repository context as needed. Report only concrete violations introduced by these changes, with file and description fields. Return a JSON array, or [] if none. Do not edit files."
+inputs = ["collect/push.diff", "collect/rules.txt"]
 output = "issues.json"
 schema = "docs_issue_array"
 
-[[modules.docs.steps]]
-id = "fix"
-type = "apply"
-prompt = "Fix only the reported documentation drift. Keep edits minimal."
-inputs = ["collect/push.diff", "review/issues.json"]
-allow_paths = ["README.md", "docs/**/*.md"]
-
-[[modules.docs.steps]]
-id = "review-required"
+[[modules.rules.steps]]
+id = "gate"
 type = "assert"
-assertion = "docs_apply_requires_manual_commit"
-inputs = ["fix/result.json"]
+python = "checks/hooks.py:assert_rules"
+inputs = ["review/issues.json"]
 ```
 
-**Want findings only?** Remove the `fix` and `review-required` steps. `ask` saves a response; findings do not block a push unless you add an assertion to evaluate them.
+`docs_issue_array` is the existing schema name for `{file, description}` findings; it works for code rules too. A missing rules file or a failed check blocks the push by default. Findings live in the run artifacts under `.git/ai-push-hooks/`.
 
-**Want test verification too?** Change the workflow list to `modules = ["docs", "verify"]` and append a module using your project's test command:
+**Want fixes too?** Add an `apply` step with the findings, your rules, and an explicit `allow_paths` list, then recheck and run tests. Applied edits are not auto-committed: review the diff, commit approved changes, and retry the push.
 
-```toml
-[[modules.verify.steps]]
-id = "tests"
-type = "exec"
-command = ["npm", "test"]
-timeout_seconds = 300
-```
+## Build Your Workflow
 
-A nonzero test exit blocks the push. For requirements or plan alignment, use project access and a prompt such as: "Compare the outgoing diff with docs/requirements.md. Identify unmet acceptance criteria and missing tests." AI review complements verification; it does not replace running the tests.
+Each module combines the steps it needs:
 
-## Extend It
+| Step | Purpose |
+| --- | --- |
+| `collect` | Gather the outgoing diff and relevant context. |
+| `ask` | Ask AI for findings or another response. |
+| `apply` | Edit a temporary workspace; propagate only allowlisted changes. |
+| `exec` | Run scripts, tests, or other actions. |
+| `assert` | Evaluate a verdict and block the push if it fails. |
 
-- **Prompts:** write them inline, load a `prompt_file`, or use a built-in prompt.
-- **Custom checks:** use argv commands or repo-local Python callbacks.
-- **Task alignment:** use the Beads collector and actions with the optional `bd` CLI.
-- **Pull requests:** compose a PR with AI and create it with the optional `gh` CLI.
-- **Opt-in steps:** gate a step with `when_env`.
+`ask` alone does not block on findings; add an `assert` gate. Combine AI review with your existing linters and tests, not instead of them. Independent analysis can run concurrently; built-in `exec`, `assert`, and `apply` steps are serialized. Trusted custom command runners, including project-access `ask` commands, are not enforced read-only.
 
-See the [configuration guide](docs/configuration.md) for settings, callbacks, and built-in handlers.
+## Choose Your AI
 
-## Control And Safety
+OpenCode defaults to **`openai/gpt-5.6-luna`**. Explicit runner profiles use their own model settings. To use Codex or Claude Code, add its profile and change `[llm].runner`:
+
+```toml
+[runners.codex]
+type = "codex"
 
-- Errors block pushes by default. Review and commit any applied edits before retrying.
-- `apply` checks file and Git state before and after copying allowlisted changes back. It does not auto-commit.
-- Runners, scripts, and callbacks are local programs, not an OS sandbox. Use only trusted configuration.
-- Repository content may be sent to your runner's model provider. Review its privacy and billing terms.
+[runners.claude]
+type = "claude"
+```
+
+Each `ask` or `apply` step can override the runner, so one tool can review and another can fix. Use model identifiers available to your provider. Other tools, including Pi, can use a [custom command runner](docs/configuration.md#custom-runners).
+
+## Control And Safety
 
-Logs and run summaries live under `.git/ai-push-hooks/`. OpenCode transcripts are captured there by default. See [Security](SECURITY.md) for access and data-handling details.
+- Errors block pushes by default. AI judgments can still miss violations or report false positives.
+- `apply` validates file and Git state and limits propagated edits to `allow_paths`. It does not auto-commit.
+- Runners, scripts, and callbacks are trusted local programs, not an OS sandbox.
+- Repository content may be sent to your model provider. Review its privacy and billing terms.
 
-To intentionally skip one push: `AI_PUSH_HOOKS_SKIP=1 git push`.
+Logs and run summaries live under `.git/ai-push-hooks/`. OpenCode transcripts are captured there by default. To intentionally skip one push: `AI_PUSH_HOOKS_SKIP=1 git push`.
 
-[Configuration](docs/configuration.md) | [Contributing](CONTRIBUTING.md) | [Changelog](CHANGELOG.md) | [MIT License](LICENSE)
+[Configuration](docs/configuration.md) | [Security](SECURITY.md) | [Contributing](CONTRIBUTING.md) | [Changelog](CHANGELOG.md) | [MIT License](LICENSE)

package/ai-push-hooks.toml

@@ -12,7 +12,7 @@ base_branch = "main"
 # Repository callbacks use python = "path/to/file.py:callable" and command
 # steps use a direct argv array; both are trusted local code.
 runner = "opencode"
-model = "openai/gpt-5.6-terra"
+model = "openai/gpt-5.6-luna"
 variant = ""
 timeout_seconds = 800
 max_parallel = 2

package/docs/configuration.md

@@ -0,0 +1,263 @@
+# Configuration
+
+Define workflows in `ai-push-hooks.toml` at the repository root. Start with the [README example](../README.md#example-check-your-rules) or the [starter configuration](../ai-push-hooks.toml).
+
+## Installation
+
+The [npm quick start](../README.md#quick-start) installs a repository-local wrapper. It needs Node 18+ and Python 3.10-3.13 on the hook's `PATH`; the npm package does not bundle Python.
+
+For pnpm:
+
+```bash
+pnpm add -D ai-push-hooks@beta
+pnpm exec ai-push-hooks init --template minimal-docs
+pnpm exec ai-push-hooks install
+```
+
+For a Python-only installation:
+
+```bash
+python -m pip install ai-push-hooks
+ai-push-hooks init --template minimal-docs
+ai-push-hooks install
+```
+
+`uv tool install ai-push-hooks` or `pipx install ai-push-hooks` can replace the pip command. npm uses the `beta` tag while the package is in beta.
+
+AI steps need the selected CLI installed and authenticated with an available model. Deterministic-only workflows do not need one. `init` and `install` refuse to overwrite existing files; `--force` explicitly replaces them.
+
+## Modules And Steps
+
+`[workflow].modules` selects the modules to run. Define each module under `modules.<name>` with a non-empty list of steps. Modules are enabled by default; set `enabled = false` to disable one.
+
+Step inputs refer to earlier artifacts in the same module: `collect/push.diff`, for example. Cross-module inputs are not supported. Independent `collect` and `ask` work may run concurrently; built-in `exec`, `assert`, and `apply` steps are serialized. Trusted custom command runners, including project-access `ask` commands, are not enforced read-only.
+
+| Field | Used by | Meaning |
+| --- | --- | --- |
+| `id` | All | Unique step name within the module. |
+| `type` | All | `collect`, `ask`, `apply`, `exec`, or `assert`. |
+| `inputs` | Non-collector steps | Earlier module-local artifacts. |
+| `when_env` | All | Run only when the named environment variable is true. |
+| `collector` | `collect` | Built-in collector name. |
+| `prompt` | `ask`, `apply` | Inline instructions. |
+| `prompt_file` | `ask`, `apply` | Repository-relative prompt file. |
+| `fallback_prompt_id` | `ask`, `apply` | Built-in prompt name. |
+| `runner` | `ask`, `apply` | Override the default runner profile. |
+| `output` | `ask` | Required response artifact filename. |
+| `schema` | `ask` | Optional JSON schema name. Omit for plain text. |
+| `allow_paths` | `apply` | Required list of permitted edit globs. |
+| `executor` | `exec` | Built-in action name. |
+| `assertion` | `assert` | Built-in assertion name. |
+| `python` | `collect`, `exec`, `assert` | Repository-local callback reference. |
+| `options` | Python steps | JSON-compatible callback options. |
+| `command` | `exec`, `assert` | Direct argv command. |
+| `stdin` | Command steps | One declared input to send on stdin. |
+| `timeout_seconds` | Command steps | Positive timeout; default `60`. |
+
+Choose one handler per deterministic step: a built-in, a callback, or a command. Prompt resolution uses `prompt`, then `prompt_file`, then `fallback_prompt_id`.
+
+`ask` produces a response, not an automatic policy verdict. Use `assert` to evaluate findings when they should block. `apply` can run without a preceding `ask`; an input ending in `issues.json` containing `[]` skips the apply step.
+
+Upgrading from 0.2.1? Rename `type = "llm"` steps to `type = "ask"`.
+
+## Runner Profiles
+
+`[llm].runner` selects the default; a step's `runner` overrides it. Referenced profiles must exist under `[runners.<name>]`, except for the implicit OpenCode default.
+
+| Profile field | Values / behavior |
+| --- | --- |
+| `type` | Required: `opencode`, `codex`, `claude`, or `command`. |
+| `model` | Runner-specific model identifier. |
+| `project_access` | `artifacts` or `project`; OpenCode defaults to `artifacts`, others to `project`. |
+| `variant` | Optional OpenCode variant. |
+| `command` | Required argv array for command runners. |
+| `prompt_transport` | Command runners: `stdin` (default) or `argv`. |
+
+Without an explicit OpenCode profile, `[llm].model` and `[llm].variant` configure it. Explicit profiles use their own model settings. `AI_PUSH_HOOKS_MODEL` overrides the selected profile's model.
+
+Artifact mode supplies collected inputs in a scratch directory. Project mode lets analysis inspect the checkout. Apply always uses a temporary staging copy, with propagation limited by `allow_paths`.
+
+OpenCode runs with isolated configuration and permissions; project/global configuration, external plugins, and MCP servers are not loaded. Codex uses read-only analysis and workspace-write apply modes. Claude Code uses separate analysis and editing permissions. Authenticate the CLI before using it in a hook.
+
+Apply requires a single pushed branch whose local commit is the checked-out `HEAD`. Staging excludes Git metadata, `AGENTS.md`, ignored files, symlinks, and special files. These controls are not an OS sandbox or an automatic rollback system. See [Security](../SECURITY.md).
+
+### Apply and manual commits
+
+`apply` is generic: it can edit any eligible checkout file matching `allow_paths`; it is not limited to Markdown. The runner edits a temporary staging copy, and only validated changes propagate back to the checkout. Those edits do not enter the commit already being pushed, and `apply` never creates a Git commit.
+
+The existing `docs_apply_requires_manual_commit` assertion is a workflow gate, not human-review enforcement. It prevents the original push from passing after `apply` changes files; it cannot prove that anyone reviewed the edits or that they conform to policy. Add it after the `apply` step when that gate is desired:
+
+```toml
+[[modules.docs.steps]]
+id = "manual-commit"
+type = "assert"
+assertion = "docs_apply_requires_manual_commit"
+inputs = ["apply/result.json"]
+```
+
+The assertion checks `apply/result.json`'s `changed_files` and intentionally blocks when edits were propagated. Review `git diff`, run the relevant checks, commit the approved changes, and retry the push. On the retry, the assertion passes when the apply step reports no changes.
+
+## Custom Runners
+
+Use a command profile for another CLI, including Pi, or your own wrapper. This example expects a local `scripts/review-agent` program that reads the prompt from stdin and writes its final response to stdout:
+
+```toml
+[runners.custom]
+type = "command"
+command = ["/absolute/path/to/scripts/review-agent"]
+prompt_transport = "stdin"
+project_access = "project"
+```
+
+Select it with `runner = "custom"` on an `ask` or `apply` step. The runner receives the full instruction and artifact packet. For apply, its working directory is the staging copy.
+
+Commands are argv arrays, not shell strings. Whole-argument placeholders are `{model}`, `{cwd}`, `{stage}`, and `{prompt}`. The `argv` transport requires exactly one `{prompt}` argument; stdin avoids exposing prompts in process listings. Custom programs inherit the user environment and own their permissions and session lifecycle.
+
+## Commands And Callbacks
+
+Command steps run in the real repository, with no implicit shell. Exit zero means success; a nonzero exit blocks the workflow. stdout, stderr, and a `result.json` report are saved as step artifacts.
+
+```toml
+[[modules.verify.steps]]
+id = "tests"
+type = "exec"
+command = ["{python}", "-m", "pytest", "-q"]
+timeout_seconds = 300
+```
+
+Available whole-argument placeholders are `{repo}`, `{python}`, and `{input:<step/artifact>}`. Input placeholders must also appear in `inputs`. Stdin is closed unless `stdin` names a declared input. Command output is bounded to 16 MiB per stream.
+
+For custom context or policy, reference a top-level synchronous Python function:
+
+```toml
+[[modules.policy.steps]]
+id = "change-size"
+type = "assert"
+python = "checks/hooks.py:check_size"
+options = { max_files = 25 }
+```
+
+In `checks/hooks.py`:
+
+```python
+from ai_push_hooks.plugins import PluginContext
+
+
+def check_size(context: PluginContext) -> dict:
+    ok = len(context.push.changed_files) <= context.options["max_files"]
+    return {"ok": ok, "message": "Change exceeds the configured file limit." if not ok else ""}
+```
+
+Add `policy` to `[workflow].modules` to enable it. Callbacks receive repository and step identifiers, push facts, input paths, options, prior module metadata, and a logger.
+
+| Callback type | Return value |
+| --- | --- |
+| `collect` | `CollectorResult` from `ai_push_hooks.plugins`, with artifacts and metadata. |
+| `exec` | JSON-serializable dictionary, saved as `result.json`. |
+| `assert` | Dictionary with boolean `ok` and optional string `message`; false blocks. |
+
+Callbacks run as trusted in-process code with already-installed dependencies. There is no callback timeout or automatic dependency installation. Collectors may run concurrently, so custom collectors must be concurrency-safe.
+
+## Built-In Handlers
+
+| Kind | Name | Purpose |
+| --- | --- | --- |
+| Collector | `docs_context` | Push diff, changed files, docs excerpts, recent commits. |
+| Collector | `beads_status_context` | Branch and Beads task context. |
+| Collector | `pr_context` | Context for a pull request. |
+| Action | `beads_alignment` | Apply supported `bd update` / `bd close` operations. |
+| Action | `gh_pr_create` | Create or reuse a PR through `gh`. |
+| Assertion | `docs_apply_requires_manual_commit` | Block after applied docs changes. |
+| Assertion | `beads_alignment_clean` | Block on unresolved task alignment. |
+
+Beads steps need the native `bd` CLI; PR creation needs `gh`. Gate optional actions with `when_env = "AI_PUSH_HOOKS_CREATE_PR"`, for example. Beads schema and database maintenance remain separate from hook execution.
+
+| JSON schema | Payload |
+| --- | --- |
+| `string_array` | Array of strings. |
+| `docs_issue_array` | Array of objects with `file` and `description`. |
+| `beads_alignment_result` | Object with optional `commands` string array. |
+| `pr_create_payload` | Object containing PR creation fields. |
+
+Built-in prompts: `docs-query-basic`, `docs-analysis-basic`, `docs-apply-basic`, `beads-plan-basic`, and `pr-compose-basic`.
+
+## Settings
+
+These optional settings supplement the workflow and runner definitions:
+
+| Section | Key | Default |
+| --- | --- | --- |
+| `general` | `enabled` | `true` |
+| `general` | `allow_push_on_error` | `false` |
+| `general` | `require_clean_worktree` | `false` |
+| `general` | `skip_on_sync_branch` | `true` |
+| `general` | `base_branch` | `"main"` |
+| `llm` | `runner` | `"opencode"` |
+| `llm` | `model` | `"openai/gpt-5.6-luna"` (implicit OpenCode profile) |
+| `llm` | `variant` | `""` |
+| `llm` | `timeout_seconds` | `800` |
+| `llm` | `max_parallel` | `2` |
+| `llm` | `json_max_retries` | `2` |
+| `llm` | `invalid_json_feedback_max_chars` | `6000` |
+| `llm` | `json_retry_new_session` | `true` |
+| `llm` | `delete_session_after_run` | `true` |
+| `llm` | `max_diff_bytes` | `180000` |
+| `llm` | `session_title_prefix` | `"ai-push-hooks"` |
+| `logging` | `level` | `"status"` (`info` and `debug` also available) |
+| `logging` | `jsonl` | `true` |
+| `logging` | `capture_llm_transcript` | `true` (OpenCode only) |
+| `logging` | `print_llm_output` | `false` |
+| `logging` | `dir` | `".git/ai-push-hooks/logs"` |
+| `logging` | `transcript_dir` | `".git/ai-push-hooks/transcripts"` |
+| `logging` | `summary_dir` | `".git/ai-push-hooks/summaries"` |
+
+Model availability depends on the provider. Select one available to your account rather than assuming the starter's model is accessible.
+
+## Environment Overrides
+
+| Variable | Effect |
+| --- | --- |
+| `AI_PUSH_HOOKS_SKIP=1` | Skip the hook before loading configuration. |
+| `AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR=1` | Log errors but allow the push. |
+| `AI_PUSH_HOOKS_REQUIRE_CLEAN=1` | Require a clean worktree. |
+| `AI_PUSH_HOOKS_ALLOW_DIRTY=1` | Allow a dirty worktree. |
+| `AI_PUSH_HOOKS_BASE_BRANCH` | Override the base branch. |
+| `AI_PUSH_HOOKS_MODEL` | Override the selected runner's model. |
+| `AI_PUSH_HOOKS_VARIANT` | Override the OpenCode variant. |
+| `AI_PUSH_HOOKS_TIMEOUT_SECONDS` | Override the runner timeout. |
+| `AI_PUSH_HOOKS_LOG_LEVEL` | Set console verbosity. |
+| `AI_PUSH_HOOKS_PRINT_LLM_OUTPUT=1` | Print normalized, redacted final responses; sensitive opt-in. |
+
+Boolean values accept `1/0`, `true/false`, `yes/no`, `y/n`, and `on/off`. Skips and fail-open settings are explicit policy choices, not successful checks.
+
+## Hook Managers
+
+The built-in `install` command creates a repository-local pre-push hook without changing Git configuration. Existing hooks require explicit `--force` replacement; shared/external paths and symlinks are refused. Keep the installed Python executable or local npm package available at its installed location.
+
+For Lefthook, use this in `lefthook.yml` instead of the built-in installer:
+
+```yaml
+pre-push:
+  commands:
+    ai-checks:
+      run: npx --no-install ai-push-hooks hook {1} {2}
+      use_stdin: true
+```
+
+Run `lefthook install`. For a Python installation, omit the `npx --no-install` prefix. Other hook managers must likewise forward Git's remote arguments, ref-update stdin, and exit status. If earlier commands consume stdin, capture it first and replay it to ai-push-hooks.
+
+To remove the generated hook, inspect `git rev-parse --git-path hooks/pre-push` and remove only the ai-push-hooks delegate or its entry in your hook manager. Preserve unrelated hook commands.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Hook does not run | Reinstall with your chosen hook manager and inspect `git config --get core.hooksPath`. |
+| Missing runner or authentication failure | Ensure the CLI is on the hook's `PATH`, authenticated, and configured with an available model. |
+| Unknown profile | Match `runner` to an existing `[runners.<name>]`. |
+| Runner capability error | Update the CLI to a version with the required adapter flags. |
+| Invalid JSON | Check the prompt and schema; invalid JSON is retried twice by default. |
+| Push blocked after edits | Review `git diff`, run checks, commit approved changes, and retry the push. |
+| Need diagnostics | Inspect `.git/ai-push-hooks/logs` and `.git/ai-push-hooks/summaries`. |
+
+For validation commands, see [Contributing](../CONTRIBUTING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {
@@ -30,7 +30,7 @@
     "ai-push-hooks": "bin/ai-push-hooks.js"
   },
   "scripts": {
-    "test": "uv run --no-project --with pytest --with build --with pip --with \"tomli; python_version < '3.11'\" pytest tests -q",
+    "test": "uv run --no-project --with \".[dev]\" python -m pytest tests -q",
     "test:npm-pack": "node tests/npm-pack-smoke.mjs"
   },
   "files": [
@@ -38,9 +38,9 @@
     "src/**/*.py",
     "vendor",
     "README.md",
+    "docs/configuration.md",
     "CHANGELOG.md",
     "SECURITY.md",
-    "run.sh",
     "pyproject.toml",
     "LICENSE",
     "ai-push-hooks.toml"

package/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=69", "wheel"]
+requires = ["setuptools>=77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.3.1"
+version = "0.3.2"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,7 +34,7 @@ Changelog = "https://github.com/shanebishop1/ai-push-hooks/blob/main/CHANGELOG.m
 ai-push-hooks = "ai_push_hooks.cli:main"
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = ["pytest>=8.0", "build", "pip", "ruff", "twine"]
 
 [tool.setuptools]
 include-package-data = true
@@ -44,3 +44,12 @@ where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"