ai-push-hooks 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-09-14
+
+This is a beta patch release. Python and npm both use `0.3.3`, the canonical
+Git tag is `v0.3.3`, 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.3` version.
+
+This is a documentation and validation patch only; it adds no runtime features.
+
+### Documentation
+
+- Added a tested deterministic postcondition recipe that distinguishes successful
+  runner execution from a verified fix, while preserving legitimate no-op applies.
+- Recorded live runner validation results for OpenCode, Claude Code, and Codex.
+- Clarified the focused pre-push use case and how the tool complements hook
+  managers, background reviewers, and broader agent workflow frameworks.
+- Documented custom-agent CLI support through the custom command runner.
+- Updated the Codex conformance check to 0.152.0 and verified live project reads
+  and allowlisted edits with `gpt-5.6-luna`.
+
 ## [0.3.2] - 2026-09-12
 
 This is a beta patch release. Python and npm both use `0.3.2`, the canonical
@@ -44,8 +64,7 @@ must select the exact `0.3.2` version.
 
 ### 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.
+- Added an agent setup skill and CI/npm beta badges.
 - 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
@@ -196,7 +215,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.2...HEAD
+[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.3...HEAD
+[0.3.3]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.2...v0.3.3
 [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

package/README.md

@@ -6,7 +6,7 @@
 
 `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.
+Use **OpenCode, Codex, Claude Code, or your own agentic CLI** 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
 
@@ -19,9 +19,11 @@ Use **OpenCode, Codex, or Claude Code** to check rules that need judgment, not j
 
 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?
+## Why This Tool?
 
-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.
+Keep your coding workflow; add a check before Git sends the commits. ai-push-hooks combines repository-specific AI checks, scripts, and explicit pass/fail gates around the outgoing diff, using your existing coding CLIs. No daemon or hosted review service is required.
+
+Use it alongside [Lefthook](https://github.com/evilmartians/lefthook) for hook management and [roborev](https://github.com/kenn-io/roborev) for background reviews. [Archon](https://github.com/coleam00/Archon) and [TAKT](https://github.com/nrslib/takt) orchestrate development tasks; this tool deliberately stays narrower. Its job is to check your rules before a push, not take over how you build the project.
 
 ## Quick Start
 
@@ -37,12 +39,6 @@ Install and authenticate your chosen AI CLI. The current `init` starter checks d
 
 [Other installation options](docs/configuration.md#installation) | [Existing hook managers](docs/configuration.md#hook-managers)
 
-## Deterministic Demo
-
-![Review, fail, fix, commit, pass: deterministic demo](https://raw.githubusercontent.com/shanebishop1/ai-push-hooks/main/docs/demo/review-fix.gif)
-
-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`.
-
 ## Example: Check Your Rules
 
 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.
@@ -103,7 +99,7 @@ inputs = ["review/issues.json"]
 
 `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 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.
+**Want fixes too?** Add an `apply` step with the findings, your rules, and an explicit `allow_paths` list, then recheck and run tests. [Runner completion is not proof that a fix landed](docs/configuration.md#deterministic-postconditions-after-apply): verify the result. Applied edits are not auto-committed: review the diff, commit approved changes, and retry the push.
 
 ## Build Your Workflow
 
@@ -121,7 +117,7 @@ Each module combines the steps it needs:
 
 ## Choose Your AI
 
-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`:
+OpenCode, Codex, and Claude Code have first-class adapters. 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]
@@ -131,13 +127,14 @@ type = "codex"
 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).
+Each `ask` or `apply` step can override the runner, so one tool can review and another can fix. **Any other agentic CLI, including Pi, can integrate through a [custom command runner](docs/configuration.md#custom-runners)**: supply a noninteractive command or a thin wrapper. Use model identifiers available to your provider.
 
 ## Control And Safety
 
 - 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.
+- Local hooks can be bypassed; retain CI for required enforcement.
 - Repository content may be sent to your model provider. Review its privacy and billing terms.
 
 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`.

package/SECURITY.md

@@ -117,7 +117,12 @@ The [0.3.0 release record](CHANGELOG.md#030---2026-09-09) documented a pinned
 Lefthook suite reporting **407 tests with no skips**, an OpenCode **1.18.29**
 contract smoke test with an in-process loopback mock provider and no external
 model call, and version/help-only checks for Codex **0.148.0** and Claude
-**2.1.220**. This is historical evidence, not a current suite result or proof
-for every provider, model, authentication mode, platform, or live `apply` path.
+**2.1.220**. The bounded validation snapshot also records Codex **0.152.0** on
+2026-09-14: its synthetic fixture verified a nonce read and an allowlisted marker
+apply followed by a deterministic postcondition. See the [runner validation
+snapshot](docs/configuration.md#live-validation-snapshot). Together, these records
+are historical or bounded evidence, not a current suite result or proof for every
+provider, model, authentication mode, platform, live `apply` path, or a general
+security guarantee.
 Treat generated-hook path checks and the Lefthook runner as integration
 safeguards, not isolation boundaries.

package/docs/configuration.md

@@ -64,6 +64,8 @@ Upgrading from 0.2.1? Rename `type = "llm"` steps to `type = "ask"`.
 
 `[llm].runner` selects the default; a step's `runner` overrides it. Referenced profiles must exist under `[runners.<name>]`, except for the implicit OpenCode default.
 
+OpenCode, Codex, and Claude are first-class adapters. The generic `command` type is for other agentic CLIs and follows the custom runner contract below.
+
 | Profile field | Values / behavior |
 | --- | --- |
 | `type` | Required: `opencode`, `codex`, `claude`, or `command`. |
@@ -81,6 +83,27 @@ OpenCode runs with isolated configuration and permissions; project/global config
 
 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).
 
+### Live validation snapshot
+
+Live read/review and apply checks on Linux:
+
+| Date | Runner (CLI; model) | Review | Apply |
+| --- | --- | --- | --- |
+| 2026-09-12 | OpenCode (1.18.29; `openai/gpt-5.6-luna`) | Passed | Passed |
+| 2026-09-12 | Claude Code (2.1.220; `sonnet`) | Passed | Passed |
+| 2026-09-14 | Codex (0.152.0; `gpt-5.6-luna`) | Passed | Passed |
+
+The Codex check read a random value from a disposable repository, then verified
+that only the allowlisted README changed. These checks establish the tested
+operations, not compatibility with every model or platform.
+
+#### Local troubleshooting: Codex sandbox
+
+For Codex 0.152, the standalone no-AI sandbox syntax is
+`codex sandbox -- /usr/bin/true`. Resolve host restrictions rather than disabling
+protections, and use a deterministic postcondition to verify the desired checkout
+outcome after an apply.
+
 ### 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.
@@ -97,9 +120,62 @@ 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.
 
+### Deterministic postconditions after apply
+
+An apply process succeeding, or reporting `changed_files = []`, is not proof that
+the requested result is present. The latter can simply mean that the apply was a
+legitimate no-op because the checkout was already correct. Add a deterministic
+postcondition after `apply` and before the manual-commit gate when the desired
+file content has a precise representation:
+
+```toml
+[general]
+require_clean_worktree = true
+
+[workflow]
+modules = ["docs"]
+
+[modules.docs]
+enabled = true
+
+[[modules.docs.steps]]
+id = "apply"
+type = "apply"
+prompt = "In the existing README.md, replace 'Release note: DRAFT.' with 'Release note: READY.' and make no other changes."
+allow_paths = ["README.md"]
+
+[[modules.docs.steps]]
+id = "postcondition"
+type = "assert"
+command = [
+  "{python}",
+  "-c",
+  "import pathlib, sys; sys.exit(0 if pathlib.Path('README.md').read_text(encoding='utf-8') == 'Release note: READY.\\n' else 1)",
+]
+inputs = ["apply/result.json"]
+
+[[modules.docs.steps]]
+id = "manual-commit"
+type = "assert"
+assertion = "docs_apply_requires_manual_commit"
+inputs = ["apply/result.json"]
+```
+
+This is an intentional synthetic example, not a recommendation to overwrite a
+real README: its fixture starts with exactly `Release note: DRAFT.\n`, and its
+desired full content is exactly `Release note: READY.\n`.
+The command is a direct argv vector rather than a Python `assert`; Python
+optimization must not be able to remove the check. The postcondition reads the
+checkout after apply, not the commit being pushed. Keep the clean-worktree
+workflow setting for the hook's starting state and the manual-commit gate for
+the intentionally dirty post-apply checkout: review the resulting diff, run
+relevant checks, commit it, and retry the push. This gate and postcondition
+still do not prove human review, semantic correctness, or that an agent
+complied with every instruction.
+
 ## 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:
+Use a `command` profile to invoke any other agentic CLI, including Pi, directly or through a thin wrapper. A wrapper can normalize JSONL events into a final response. The runner must be noninteractive: read the prompt from stdin or argv, write only the final response to stdout, and use exit codes to report success or failure.
 
 ```toml
 [runners.custom]
@@ -111,7 +187,7 @@ 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 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's environment, including authentication variables, and manage their own permissions and session setup/cleanup. For apply, the working directory is the staging copy.
 
 ## Commands And Callbacks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.3.2"
+version = "0.3.3"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"