ai-push-hooks 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -4,6 +4,72 @@ 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
+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 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
+  the local-only runner verification report.
+
 ## [0.3.1] - 2026-09-10
 
 ### Changed
@@ -149,7 +215,9 @@ 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.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
 [0.2.1]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.2.0...v0.2.1

package/README.md

@@ -1,134 +1,142 @@
 # 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, 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
+
+| 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 This Tool?
+
+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
 
+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
+## Example: Check Your Rules
 
-A workflow is a list of modules. Each module combines the steps it needs:
+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.
 
-| 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. |
+In `checks/hooks.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.
+```python
+import json
 
-## Choose Your AI
+from ai_push_hooks.plugins import CollectorResult, PluginContext
 
-Set the default runner in `ai-push-hooks.toml`. Change it to `codex` or `claude` to switch tools:
 
-```toml
-[llm]
-runner = "opencode"
-
-[runners.opencode]
-type = "opencode"
-model = "provider/model-id" # Replace with an available OpenCode model.
-project_access = "artifacts"
+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"),
+    })
 
-[runners.codex]
-type = "codex"
 
-[runners.claude]
-type = "claude"
+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."}
 ```
 
-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.
-
-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. [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.
 
-```toml
-[[modules.verify.steps]]
-id = "tests"
-type = "exec"
-command = ["npm", "test"]
-timeout_seconds = 300
-```
+## Build Your Workflow
+
+Each module combines the steps it needs:
+
+| 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. |
+
+`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.
 
-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.
+## Choose Your AI
+
+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`:
 
-## Extend It
+```toml
+[runners.codex]
+type = "codex"
 
-- **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`.
+[runners.claude]
+type = "claude"
+```
 
-See the [configuration guide](docs/configuration.md) for settings, callbacks, and built-in handlers.
+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. 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.
-
-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.
+- 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.
 
-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/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/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