ai-push-hooks 0.1.18 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+No changes yet.
+
+## [0.2.0] - 2026-09-06
+
+This is a beta release. Python and npm both use `0.2.0`, the canonical Git tag
+is `v0.2.0`, npm uses the `beta` dist-tag, and GitHub marks the release as a
+prerelease. PyPI does not provide package channels, so Python users must select
+the exact `0.2.0` version rather than a PyPI beta channel.
+
+### Added
+
+- Added a safe repo-local `ai-push-hooks install [--force]` delegate that
+  preserves hook arguments, stdin, and exit status, refuses unsafe or shared
+  hook targets, and never changes Git configuration.
+
+### Changed
+
+- Hardened OpenCode execution with isolated configuration, denied tools for read-only work, and allowlisted temporary workspaces for apply steps.
+- Added fail-closed path, symlink, file-mode, artifact, Git metadata, and concurrent-change validation around model-assisted edits.
+- Restricted prompt files and runtime storage to validated repository-owned locations and private filesystem permissions.
+- Updated the default OpenCode model and release workflow dependencies.
+- Added CI/package validation, community health files, public package metadata, and post-publication GitHub Releases.
+- Documented the shortest installed wheel/npm onboarding path, the full-featured
+  Lefthook alternative, safe removal, failure/fail-open/skip semantics, and the
+  Python requirement for npm installs.
+- Recorded a limited synthetic provider preview: OpenCode 1.18.29 with
+  `opencode/muse-spark-1.3-contributor-free`, which was listed as free at test
+  time; synthetic query/analyze passed at zero reported cost. Free-model
+  availability can change. This does not claim all providers/models or live
+  apply.
+
+### Compatibility and limitations
+
+- The candidate evidence includes macOS Darwin 24.6.0 arm64 with Python
+  3.12.13, Node 24.19.0, npm 10.9.2, Git 2.55.0, Ruff 0.13.3, OpenCode
+  1.18.29, `gh` 2.93.0, and `bd` 1.2.2. Python 3.10–3.13 and Node 18+ remain
+  declared ranges; Windows has no native beta evidence and is untested/not
+  supported for this beta.
+- The published `0.1.19` registry artifacts retain their historical provenance;
+  this release does not republish, move, or overwrite that version.
+
+## [0.1.19] - 2026-07-13
+
+### Added
+
+- Added configurable base-branch support for pull-request workflows.
+- Added packed npm-package smoke coverage.
+
+### Fixed
+
+- Added Python 3.10 TOML compatibility and fixed npm-local hook command resolution.
+- 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.2.0...HEAD
+[0.2.0]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.1.19...v0.2.0
+[0.1.19]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.1.18...v0.1.19

package/README.md

@@ -1,75 +1,342 @@
 # ai-push-hooks
 
-`ai-push-hooks` is a configurable pre-push workflow runner for local Git repositories.
+`ai-push-hooks` catches repository drift before it reaches a remote. It turns `git push` into a configurable workflow that can inspect the exact outgoing diff, ask an LLM for structured findings, apply narrowly allowlisted documentation fixes, run deterministic actions, and block the push until changes are reviewed and committed.
 
-It runs module-based steps (collect, LLM, apply, exec, assert) before push so you can automate checks and optional repo maintenance tasks.
+Use it to keep docs aligned with code, check branch/task consistency, or prepare pull requests without replacing your project's ordinary lint, test, and build checks. Workflows are assembled from `collect`, `llm`, `apply`, `exec`, and `assert` steps and default to failing closed.
 
-## Install
+## Quick start: repo-local hook
 
-### Python
+### Prerequisites
+
+- [Git](https://git-scm.com/downloads) and a POSIX shell for the generated hook.
+- [Python 3.10–3.13](https://www.python.org/downloads/). Python is required even when installing the npm wrapper. The wrapper probes Python 3.14, 3.13, 3.12, 3.11, 3.10, then `python`; the 3.14 probe is not a beta support claim. Python 3.10 additionally needs the `tomli` package available to that interpreter.
+- [OpenCode](https://opencode.ai/docs/#install) is optional for workflows that use only deterministic steps, but the `minimal-docs` starter uses `llm` and `apply`. Those steps also need a provider/model and authentication; check with `opencode auth list`.
+- [GitHub CLI (`gh`)](https://cli.github.com/manual/installation) is optional and needed only for `gh_pr_create`.
+- [Beads (`bd`)](https://github.com/steveyegge/beads) is optional and needed only for Beads alignment steps.
+- [Lefthook](https://lefthook.dev/installation/) and [Mise](https://mise.jdx.dev/getting-started.html) are optional hook-manager/tool-version alternatives described below.
+
+### Install ai-push-hooks
+
+This is the shortest path. It installs the package, writes the exact starter
+configuration filename, and installs a repository-local `pre-push` delegate:
 
 ```bash
-uv tool install ai-push-hooks
-# or
-pipx install ai-push-hooks
+python -m pip install ai-push-hooks==0.2.0
+ai-push-hooks init --template minimal-docs
+ai-push-hooks install
 ```
 
-### Node (wrapper around Python package)
+The installed-artifact tests exercise the equivalent install and hook sequence
+with wheel and npm artifacts in disposable repositories, including a real
+local push that succeeds and a second push that is rejected without changing
+the bare remote. The first command above can instead be `uv tool install
+ai-push-hooks` or `pipx install ai-push-hooks` when using an isolated
+application environment.
+
+These instructions describe the `0.2.0` beta release. npm exposes it through
+the `beta` dist-tag; PyPI has no separate beta channel, so Python installation
+must select the exact `0.2.0` version. Published `0.1.19` artifacts retain
+historical provenance and must not be assumed to contain this release's
+`install` command.
+
+The starter config currently writes `openai/gpt-5.6-terra` as its model value;
+availability and authentication are provider-dependent. To use a free OpenCode
+Zen model, run `opencode models opencode`, choose a model currently marked
+free, and set `[llm].model` to that full identifier. Free-model availability
+changes over time, so do not treat the model used in the recorded preview below
+as a permanent recommendation or default.
+
+For npm or pnpm, install and invoke the wrapper locally:
 
 ```bash
-npm install --save-dev ai-push-hooks
-# or
-pnpm add -D ai-push-hooks
+npm install --save-dev ai-push-hooks@beta
+npx --no-install ai-push-hooks init --template minimal-docs
+npx --no-install ai-push-hooks install
+# or: pnpm add -D ai-push-hooks && pnpm exec ai-push-hooks install
 ```
 
-Requirements:
+Use `ai-push-hooks@0.2.0` instead of `@beta` when an exact npm version pin is
+required.
 
-- [Python 3.10+](https://www.python.org/downloads/) (`python3` or `python`) is required. The npm package is a wrapper around the Python CLI, so Python is still required when installed through npm/pnpm.
-- [OpenCode](https://github.com/anomalyco/opencode) is required for `llm` and `apply` steps.
-- [GitHub CLI (`gh`)](https://cli.github.com/manual/installation) is required only if you use PR creation via `gh_pr_create`.
+The npm package does not contain a Python runtime. Ensure the Python
+requirement above is on `PATH` for the hook process; on Python 3.10 install
+`tomli` in that same environment. `npx --no-install` avoids an accidental
+registry lookup or global-package fallback.
 
-## Quick start
+`install` resolves Git's effective hook path without changing Git
+configuration. It accepts `install [--force]`, creates missing repository-local
+hook directories, writes atomically, and makes the delegate executable. An
+existing regular hook is refused unless `--force` is explicit; symlinks,
+reparse points, FIFOs, directories, external/shared `core.hooksPath` values,
+and linked-worktree shared hooks are refused even with `--force`. `--force`
+replaces a regular existing hook; it does not merge or back it up. Inspect a
+hook before using it and keep a copy if it contains work you need.
 
-1. Install by following the steps above.
-2. Generate a starter config:
+The generated delegate preserves Git's hook arguments, standard input, and
+exit status. When installed through the local npm wrapper, it records the
+absolute Node and package-script paths, so Git does not need
+`node_modules/.bin` on `PATH`; keep that local package installation in place.
+Python console installs similarly record their executable when it can be
+resolved. The fallback delegate fails clearly with status 127 if
+`ai-push-hooks` is not on the hook process's `PATH`.
 
-   Python tool install (`uv tool` / `pipx`):
+### Mise (pinned tool option)
 
-   ```bash
-   ai-push-hooks init --template minimal-docs
-   ```
+Pin an approved published release in the consuming repository:
 
-   npm/pnpm local install:
+```bash
+mise use npm:ai-push-hooks@0.2.0
+```
+
+This adds the following project-level tool entry to `mise.toml` and installs it:
+
+```toml
+[tools]
+"npm:ai-push-hooks" = "0.2.0"
+```
 
-   ```bash
-   npx ai-push-hooks init --template minimal-docs
-   # or
-   pnpm exec ai-push-hooks init --template minimal-docs
-   ```
+After checking in `mise.toml`, other contributors can install the pinned tool with `mise install`.
 
-3. Configure modules and steps in [Configuration reference](#configuration-reference).
-4. Wire it into your pre-push hook manager. Lefthook example:
+### OpenCode isolation limits
 
-   ```yaml
-   pre-push:
-     commands:
-       ai-push-hooks:
-         run: ai-push-hooks hook {1} {2}
-   ```
+OpenCode runs in `--pure` mode with project configuration disabled, isolated home/config/cache/state directories, sharing disabled, and an ai-push-hooks-owned custom agent configuration. Read-only steps run in an empty scratch directory, receive only hook-owned artifacts through `--file`, and have every tool denied. Apply steps run against a private temporary workspace containing only unignored regular files matching `allow_paths`; their agent permits only reads and allowlisted edits in that workspace. Casefolded, Unicode-normalized `.git` and `AGENTS.md` paths are always protected.
 
-   In Lefthook, `{1}` is the remote name and `{2}` is the remote URL from Git's `pre-push` hook args.
+Global and repository OpenCode instructions, custom agents, MCP servers, formatters, LSP configuration, sharing, and plugins are not inherited. The existing XDG data directory is retained for OpenCode authentication/session state, and recognized provider environment variables are forwarded. Custom providers defined only in global OpenCode configuration are therefore unsupported; use a built-in provider with OpenCode auth state or environment credentials.
+
+After OpenCode session finalization, apply verifies that the Git-visible checkout, index, current-worktree control state, and critical shared `HEAD`/config/packed-refs/refs/hooks state still match their baselines. Pre-existing symlinks in monitored Git metadata fail closed before OpenCode runs, and symlinks introduced during execution fail before propagation. Apply then preflights every destination against its exact baseline type, content digest, and mode before propagating anything, performs atomic file replacement, and verifies the resulting checkout and protected Git state again. Safe existing ordinary `rwx` modes are preserved, existing special bits are stripped, new or group/world-writable modes become owner-only, and staged files carrying setuid/setgid/sticky bits are rejected before any propagation. Hook-owned runtime files default to `0600` and runtime directories to `0700`.
+
+These controls are OpenCode permission and workspace isolation, not an operating-system sandbox. Compare-and-swap preflight minimizes lost updates but cannot make the interval between preflight and filesystem replacement atomic against an independent local process. Ignored worktree trees, Git object/LFS stores, shared reflogs, and metadata belonging only to other linked worktrees are intentionally excluded from bounded snapshots; direct changes there may not be detected. Critical shared refs/config/hooks remain monitored. Automatic rollback is avoided so pre-existing user changes are not overwritten.
+
+## Full-featured alternative: Lefthook
+
+Use Lefthook when the repository needs several hook commands, shared hook
+configuration, or repository-managed installation. Keep one final
+`ai-push-hooks hook` call and forward Git's pre-push input:
+
+Create `scripts/hooks/pre-push-runner.sh` in the consuming repository with:
+
+```yaml
+pre-push:
+  commands:
+    repository-pre-push:
+      run: bash scripts/hooks/pre-push-runner.sh {1} {2}
+      use_stdin: true
+```
+
+The runner captures stdin before deterministic checks consume it, then replays
+it to the tool:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+remote_name="${1:-}"
+remote_url="${2:-}"
+push_stdin="$(mktemp)"
+trap 'rm -f "$push_stdin"' EXIT
+cat >"$push_stdin"
+git diff --check
+mise exec -- ai-push-hooks hook "$remote_name" "$remote_url" <"$push_stdin"
+```
 
-5. Push as usual. The workflow runs automatically before push completes.
+Install and verify Lefthook in the consuming repository:
+
+```bash
+lefthook version
+chmod +x scripts/hooks/pre-push-runner.sh
+lefthook install
+test -x "$(git rev-parse --git-path hooks/pre-push)" && echo "pre-push hook installed"
+```
+
+`use_stdin: true` forwards Git's ref-update stream; `{1}` and `{2}` are the
+remote name and URL. This is the full-featured alternative to the small
+repo-local `install` delegate. Do not install both managers for the same hook
+unless their chaining is deliberate. The repository's deterministic installed
+hook coverage validates the delegate contract; Lefthook remains the tested
+repository-owned integration pattern and should be exercised with the commands
+above in each consuming repository.
+
+Configure modules and steps in the [configuration reference](#configuration-reference), then push as usual. If `apply` edits an allowlisted file, the starter assertion blocks that push so you can inspect `git diff`, validate, commit the approved edit, and push again.
+
+## Troubleshooting
+
+- **`opencode is required but not installed`:** install OpenCode and ensure `opencode` (or `opencode-cli`) is on `PATH` for the Git hook process.
+- **Provider/model authentication fails:** run `opencode auth list`, authenticate a built-in provider, and verify `[llm].model`. Project/global custom-provider configuration is intentionally not loaded; see [OpenCode isolation limits](#opencode-isolation-limits).
+- **The hook does not run:** rerun `lefthook install`, check `git config --get core.hooksPath`, and verify the pre-push path with the command above.
+- **The push is blocked after docs changed:** this is the expected edit-review-commit flow. Review `git diff`, validate and commit the changes, then push again.
+- **Find logs or transcripts:** inspect `.git/ai-push-hooks/logs`, `.git/ai-push-hooks/summaries`, and (when enabled) `.git/ai-push-hooks/transcripts`.
+- **Temporarily skip intentionally:** set `AI_PUSH_HOOKS_SKIP=1` for one invocation. Treat bypasses as an explicit project-policy decision.
+
+### Failure, fail-open, and skip semantics
+
+- Fail closed is the default: configuration, collection, model, apply, exec,
+  and assertion errors return nonzero and block the push. A rejected push does
+  not update the remote.
+- Set `[general].allow_push_on_error = true`, or use
+  `AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR=1`, only as an explicit fail-open policy.
+  The error is still logged and a warning is emitted, but the push is allowed.
+- `AI_PUSH_HOOKS_SKIP=1` exits before repository/config access and allows that
+  invocation. `general.enabled = false` is a configured disable after config
+  loading/log initialization. Neither path validates or runs the workflow.
+- `skip_on_sync_branch = true` can skip configured sync-branch context, and
+  step/module conditions can report a normal skip. A skip is not a successful
+  model or apply result.
+
+Git supplies hook stdin as one line per ref update:
+`<local-ref> <local-object-id> <remote-ref> <remote-object-id>`. New remote
+refs use a zero object ID (40 zeroes for the tested SHA-1 repositories); deletion
+uses `(delete)` and a zero local ID. The hook rejects malformed input, unknown
+objects, and multiple non-deleted branch updates rather than silently choosing
+a branch.
+
+### Safe removal of the generated hook
+
+`install` has no uninstall command and never edits Git configuration. To remove
+only its delegate, first inspect the effective target and content:
+
+```bash
+hook="$(git rev-parse --git-path hooks)/pre-push"
+if [ -f "$hook" ]; then sed -n '1,20p' "$hook"; fi
+```
+
+For an exact check before removal, use the installed Python package rather than
+matching only a filename:
+
+```bash
+python - "$hook" <<'PY'
+import pathlib
+import sys
+
+from ai_push_hooks.install import pre_push_hook_script
+
+path = pathlib.Path(sys.argv[1])
+if not path.is_file() or path.is_symlink():
+    raise SystemExit("not a regular hook; nothing removed")
+if path.read_text(encoding="utf-8") != pre_push_hook_script():
+    raise SystemExit("hook is not the ai-push-hooks delegate; nothing removed")
+path.unlink()
+print(f"removed {path}")
+PY
+```
+
+Remove it only after confirming it is the generated `ai-push-hooks` delegate,
+not a Lefthook or shared hook. If it contains other commands, preserve it and
+remove only the documented ai-push-hooks entry instead. Do not run `rm` on an
+uninspected `pre-push` path.
+
+## Security and privacy
+
+Repository diffs, selected context, and prompts may be sent by OpenCode to the configured model provider. Review that provider's data-handling terms and do not include secrets in commits or prompts. Transcripts are stored locally by default under `.git/ai-push-hooks/transcripts`; sharing is disabled and OpenCode sessions are deleted after each run by default. If transcript export fails, the run warns and still follows the configured deletion policy; do not assume an export exists. See [SECURITY.md](SECURITY.md) for reporting, the threat model, data handling, and sandbox limitations.
+
+### BR-06 provider evidence (limited preview)
+
+At the time of the recorded synthetic provider run, OpenCode **1.18.29** listed
+`opencode/muse-spark-1.3-contributor-free` as free. Synthetic `query` and
+`analyze` steps passed at **zero reported cost**. This is evidence for that
+specific OpenCode/model path and synthetic inputs only; it does not establish
+that every model, provider, authentication mode, or live `apply` operation is
+compatible. Discover the current catalog with `opencode models opencode` and
+verify pricing before each run; free models can be renamed, replaced, or
+removed. The tested identifier is historical evidence, not a new default or a
+promise of future availability. Review provider billing, retention, and
+transmission terms before using repository content.
+
+## Tested matrix and beta boundary
+
+The current candidate was exercised on **macOS Darwin 24.6.0 arm64** with
+Python **3.12.13**, Node **24.19.0**, npm **10.9.2**, Git **2.55.0**, Ruff
+**0.13.3**, OpenCode **1.18.29**, `gh` **2.93.0**, and `bd` **1.2.2**. The
+wheel and packed npm installed-hook tests use disposable repositories, full
+40-character Git object IDs, a local bare remote, and a minimal PATH. The
+Lefthook **2.1.9** was also run in a disposable repository to install a
+pre-push hook and verify argument/stdin forwarding. The real OpenCode contract
+also passed in a Linux arm64 Docker container launched from this macOS host.
+Python 3.10, 3.11, and 3.13 and Node 18 were not available in this validation
+environment and are not claimed as locally run; their jobs remain part of the
+GitHub Actions matrix.
+
+Prior recorded BR evidence also covers the real OpenCode 1.18.29 CLI with a
+loopback mock provider inside a Linux Docker runtime with networking disabled.
+That is mock-provider permission/workspace evidence, not live-provider or
+operating-system-sandbox evidence.
+
+Validation results for this snapshot are **273 passed, 1 skipped** for the full
+Python suite, **8 passed** for install-unit coverage, **2 passed** for installed
+wheel and npm hook coverage against the exact release artifacts, a passing
+`npm run test:npm-pack`, and a passing Lefthook 2.1.9 disposable
+argument/stdin-forwarding check. The Docker contract passed against the real
+OpenCode 1.18.29 CLI with runtime networking disabled and a loopback mock
+provider.
+
+Python 3.10–3.13 and Node 18+ remain the declared compatibility ranges, not a
+claim that every patch/platform combination has passed. Windows has no native
+beta evidence and is explicitly untested/not supported for this beta. The
+generated hook and documented runner require a POSIX shell; defensive path
+handling is not Windows validation.
+
+## Synthetic demo and evidence
+
+For a no-secrets, no-external-model-call wiring/permission demo, run:
+
+```bash
+bash scripts/opencode-contract-smoke.sh
+```
+
+It builds a disposable image, starts only an in-process loopback mock provider,
+and drives real OpenCode 1.18.29 through a synthetic repository. Runtime
+networking is disabled, so no external model call is possible; the initial
+Docker build/setup may need network access to fetch its pinned inputs. It shows
+the allowlisted `README.md` edit, denied outside/protected edits, and unchanged
+protected Git metadata. This is **wiring and permission evidence only**, not a
+live-provider demo or OS-sandbox claim; it exits 2 when Docker is unavailable.
+
+For installed hook wiring without any model/provider call:
+
+```bash
+python -m pytest -q tests/test_installed_hook_e2e.py
+npm run test:npm-pack
+```
+
+These disposable fixtures show a successful local push followed by a
+fail-closed rejection. The actual BR-06 provider preview is documented above;
+it used synthetic query/analyze inputs and must not be presented as fabricated
+provider output or as evidence for live `apply`.
+
+## Portfolio case study: bounded documentation maintenance
+
+**Problem.** A pushed code change can make repository documentation stale
+before review notices it. The hook inspects the outgoing ref range rather than
+the checked-out branch alone.
+
+**Architecture and tradeoffs.** Deterministic `collect` steps establish diff,
+changed-file, and repository context before `llm` query/analyze steps. An
+`apply` step receives a private workspace and a narrow docs allowlist; the
+assertion then blocks the push for human review and commit. `exec` and `assert`
+remain available for deterministic repository actions. This ordering limits
+model scope without pretending to provide an OS sandbox.
+
+**Evidence.** The real OpenCode 1.18.29 mock-provider contract found a
+version-specific permission mapping (`write` requests `edit`) and covers
+allowlisted propagation plus protected Git metadata. The BR-06 live synthetic
+preview used `opencode/muse-spark-1.3-contributor-free` for query/analyze at
+zero reported cost; it is not evidence for all providers/models or live apply.
+Installed wheel/npm tests cover hook wiring, a successful local push, and a
+fail-closed rejection. The Docker contract was not rerun in this environment.
+
+**Limitations.** Provider availability, billing, retention, OS-level access,
+ignored trees, shared metadata, and independent filesystem races remain outside
+the product guarantee. Review, validate, and commit any proposed edit; this is
+not unattended autonomous maintenance.
 
 ## Commands
 
-If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm exec`.
+If installed as a local npm/pnpm dependency, run commands with `npx --no-install` or `pnpm exec`.
 
 | Command | What it does |
 | --- | --- |
 | `ai-push-hooks hook <remote-name> <remote-url>` | Runs the configured pre-push workflow. |
 | `ai-push-hooks init --template minimal-docs` | Writes `ai-push-hooks.toml` starter config. |
 | `ai-push-hooks init --template minimal-docs --force` | Overwrites an existing config file. |
+| `ai-push-hooks install [--force]` | Installs a repo-local executable pre-push delegate; `--force` replaces a regular existing hook. |
 
 ## Configuration overview
 
@@ -99,13 +366,14 @@ If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm ex
 | `allow_push_on_error` | bool | `false` | If `true`, push continues even when workflow fails. |
 | `require_clean_worktree` | bool | `false` | If `true`, aborts when local changes exist. |
 | `skip_on_sync_branch` | bool | `true` | If `true`, skips on sync branch/worktree context. |
+| `base_branch` | string | `"main"` | Base branch used for new-branch range fallback and default PR base/context. |
 
 ### `[llm]`
 
 | Key | Type | Default | Description |
 | --- | --- | --- | --- |
 | `runner` | string | `"opencode"` | LLM runner label (currently OpenCode flow). |
-| `model` | string | `"openai/gpt-5.3-codex"` | Model passed to OpenCode. |
+| `model` | string | `"openai/gpt-5.6-terra"` | Model passed to OpenCode. |
 | `variant` | string | `""` | Optional OpenCode variant. |
 | `timeout_seconds` | int | `800` | Timeout per LLM invocation and related OpenCode calls. |
 | `max_parallel` | int | `2` | Max concurrent read-only steps (`collect`, `llm`). |
@@ -151,7 +419,7 @@ If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm ex
 | `output` | string | yes | `llm` | Output artifact filename (often `.json`). |
 | `schema` | string | no | `llm` | Validates parsed model output shape. |
 | `prompt` | string | conditional | `llm`, `apply` | Highest-priority prompt source. |
-| `prompt_file` | string | conditional | `llm`, `apply` | Repo-relative or absolute prompt file path. |
+| `prompt_file` | string | conditional | `llm`, `apply` | Repo-relative prompt file path; absolute, traversing, and symlinked paths are rejected. |
 | `fallback_prompt_id` | string | conditional | `llm`, `apply` | Built-in prompt ID used when no higher source resolves. |
 | `collector` | string | yes | `collect` | Collector handler ID. |
 | `allow_paths` | array of strings | yes | `apply` | File glob allowlist for edits. |
@@ -161,6 +429,8 @@ If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm ex
 
 `llm` and `apply` are promptable step types: at least one of `prompt`, `prompt_file`, or `fallback_prompt_id` must be set.
 
+Artifact references in `inputs` are module-local. Use `<step>/<artifact>` to reference an artifact produced by an earlier step in the same module (for example, `collect/push.diff` or `analyze/issues.json`). Cross-module references such as `docs:collect/push.diff` are not currently supported.
+
 ### Supported handler and schema values
 
 #### Collectors
@@ -214,6 +484,7 @@ Boolean env parsing accepts: `1`, `true`, `yes`, `y`, `on` and `0`, `false`, `no
 | `AI_PUSH_HOOKS_ALLOW_PUSH_ON_ERROR` | Overrides `general.allow_push_on_error`. |
 | `AI_PUSH_HOOKS_REQUIRE_CLEAN` | Overrides `general.require_clean_worktree`. |
 | `AI_PUSH_HOOKS_ALLOW_DIRTY` | If true, forces `general.require_clean_worktree = false`. |
+| `AI_PUSH_HOOKS_BASE_BRANCH` | Overrides `general.base_branch`. |
 | `AI_PUSH_HOOKS_LOG_LEVEL` | Overrides `logging.level`. |
 | `AI_PUSH_HOOKS_PRINT_LLM_OUTPUT` | Overrides `logging.print_llm_output`. |
 | `AI_PUSH_HOOKS_MODEL` | Overrides `llm.model`. |

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability. Report it privately with a [GitHub Security Advisory](https://github.com/shanebishop1/ai-push-hooks/security/advisories/new), including affected versions, impact, reproduction details, and any suggested mitigation. Remove credentials, proprietary source, and unneeded transcript content. Maintainers will acknowledge the report, investigate it, and coordinate disclosure and a fix through the advisory. Only the latest release is actively supported with security fixes.
+
+## Threat model and data handling
+
+ai-push-hooks treats repository content, Git paths and metadata, configuration, model output, and concurrent local filesystem changes as potentially unsafe. Its controls constrain model-visible inputs and apply destinations, protect Git metadata and instruction files, validate filesystem state before propagation, and fail closed by default. They are designed to prevent accidental or model-directed changes outside configured boundaries, not to protect against a malicious user or process with the same operating-system permissions.
+
+OpenCode is a separate local process and communicates with the model provider selected in `[llm].model`. Diffs, changed-file context, prompts, and step artifacts can therefore leave the machine under that provider's terms. ai-push-hooks forwards recognized provider credential environment variables and retains OpenCode's existing authentication data directory, but disables sharing and does not inherit project/global plugins, MCP servers, instructions, or custom-provider configuration. Do not commit secrets, and review provider retention and privacy policies before use on sensitive repositories.
+
+Hook logs, summaries, run artifacts, and transcripts are stored locally under `.git/ai-push-hooks/` with private runtime permissions. Transcript capture defaults to **on** at `.git/ai-push-hooks/transcripts`; set `logging.capture_llm_transcript = false` to disable it. OpenCode session deletion defaults to on, but provider-side retention is controlled by the provider.
+
+Transcript export is best effort. If export fails or produces no usable output,
+the run emits a warning and still applies the configured session-deletion
+policy; it does not claim that a transcript was captured. A provider may have
+already received the request even when local export fails. Do not use local
+transcript files as proof that provider-side data was deleted.
+
+## Sandbox limitation
+
+OpenCode permissions and temporary-workspace isolation are **not an operating-system sandbox**. The process retains the invoking user's OS-level access, and bounded snapshots cannot observe every ignored path, Git object/LFS store, shared reflog, other linked-worktree metadata, or race with an independent local process. Use an OS sandbox, container, VM, or dedicated low-privilege account when stronger isolation is required. See the README's [OpenCode isolation limits](README.md#opencode-isolation-limits) for the detailed guarantees and exclusions.
+
+## Tested security boundary
+
+The beta evidence covers the real OpenCode **1.18.29** permission contract in a
+no-network Docker fixture and a limited synthetic provider run using a model
+that was listed as free at test time,
+`opencode/muse-spark-1.3-contributor-free`. Free-model catalogs and pricing can
+change; verify the current catalog before use. This evidence does not cover
+every provider, model, authentication mode, or live `apply` path. Windows has
+no native beta evidence. Treat the generated hook's repository-local path
+checks and the Lefthook runner as integration safeguards, not isolation
+boundaries.

package/ai-push-hooks.toml

@@ -3,10 +3,11 @@ enabled = true
 allow_push_on_error = false
 require_clean_worktree = false
 skip_on_sync_branch = true
+base_branch = "main"
 
 [llm]
 runner = "opencode"
-model = "openai/gpt-5.3-codex"
+model = "openai/gpt-5.6-terra"
 variant = ""
 timeout_seconds = 800
 max_parallel = 2

package/bin/ai-push-hooks.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 
 const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
 const path = require('node:path');
 
 const packageRoot = path.resolve(__dirname, '..');
 const srcDir = path.join(packageRoot, 'src');
 const args = ['-m', 'ai_push_hooks', ...process.argv.slice(2)];
+const pythonCommands = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3', 'python'];
 
 function buildEnv() {
   const env = { ...process.env };
+  env.AI_PUSH_HOOKS_NODE_EXECUTABLE = process.execPath;
+  env.AI_PUSH_HOOKS_NODE_SCRIPT = fs.realpathSync(__filename);
   env.PYTHONPATH = env.PYTHONPATH
     ? `${srcDir}${path.delimiter}${env.PYTHONPATH}`
     : srcDir;
@@ -22,14 +26,25 @@ function run(command) {
   });
 }
 
-let result = run('python3');
-if (result.error && result.error.code === 'ENOENT') {
-  result = run('python');
+function canRunPackage(command) {
+  const check = spawnSync(
+    command,
+    [
+      '-c',
+      'import sys; assert sys.version_info >= (3, 10); __import__("tomllib" if sys.version_info >= (3, 11) else "tomli")',
+    ],
+    { stdio: 'ignore' },
+  );
+  return check.status === 0;
 }
 
-if (result.error && result.error.code === 'ENOENT') {
-  console.error('[ai-push-hooks] python3/python is required but not installed.');
+const pythonCommand = pythonCommands.find(canRunPackage);
+if (!pythonCommand) {
+  console.error(
+    '[ai-push-hooks] Python 3.11+ is required for npm installs. Python 3.10 can be used if tomli is installed.',
+  );
   process.exit(1);
 }
 
+const result = run(pythonCommand);
 process.exit(typeof result.status === 'number' ? result.status : 1);

package/package.json

@@ -1,22 +1,44 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.1.18",
-  "description": "Modular AI push-hook workflow runner",
+  "version": "0.2.0",
+  "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
+  "author": {
+    "name": "Shane Bishop"
+  },
+  "homepage": "https://github.com/shanebishop1/ai-push-hooks#readme",
+  "bugs": {
+    "url": "https://github.com/shanebishop1/ai-push-hooks/issues"
+  },
+  "keywords": [
+    "git",
+    "git-hooks",
+    "pre-push",
+    "ai",
+    "llm",
+    "opencode",
+    "lefthook",
+    "documentation",
+    "developer-tools",
+    "automation"
+  ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/shanebishop1/ai-push-hooks"
+    "url": "git+https://github.com/shanebishop1/ai-push-hooks.git"
   },
   "bin": {
     "ai-push-hooks": "bin/ai-push-hooks.js"
   },
   "scripts": {
-    "test": "uv run --with pytest pytest tests -q"
+    "test": "uv run --no-project --with pytest pytest tests -q",
+    "test:npm-pack": "node tests/npm-pack-smoke.mjs"
   },
   "files": [
     "bin",
     "src/**/*.py",
     "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
     "run.sh",
     "pyproject.toml",
     "LICENSE",