ai-push-hooks 0.1.17 → 0.1.19

package/README.md

@@ -6,6 +6,23 @@ It runs module-based steps (collect, LLM, apply, exec, assert) before push so yo
 
 ## Install
 
+### Mise (recommended for repository hooks)
+
+Pin the currently published release in the consuming repository:
+
+```bash
+mise use npm:ai-push-hooks@0.1.19
+```
+
+This adds the following project-level tool entry to `mise.toml` and installs it:
+
+```toml
+[tools]
+"npm:ai-push-hooks" = "0.1.19"
+```
+
+After checking in `mise.toml`, other contributors can install the pinned tool with `mise install`.
+
 ### Python
 
 ```bash
@@ -24,32 +41,63 @@ pnpm add -D ai-push-hooks
 
 Requirements:
 
-- [Python 3.10+](https://www.python.org/downloads/) (`python3` or `python`) is required, including npm installs.
-- [OpenCode CLI](https://github.com/sst/opencode) is required for `llm` and `apply` steps. The expected executable is `opencode`; `opencode-cli` is also accepted for compatibility.
+- [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`.
 
 ## Quick start
 
-1. Install the CLI.
+1. Add the pinned Mise tool by following [Mise installation](#mise-recommended-for-repository-hooks) above.
 2. Generate a starter config:
 
    ```bash
-   ai-push-hooks init --template minimal-docs
+   mise exec -- ai-push-hooks init --template minimal-docs
    ```
 
-3. Wire it into Lefthook:
+3. Add the single repository-owned runner at `scripts/hooks/pre-push-runner.sh`:
+
+   ```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"
+
+   # Run deterministic quality checks first. Replace these with the repository's checks.
+   npm run lint
+   npm test
+
+   # Keep ai-push-hooks as the single final phase and replay Git's pre-push input.
+   mise exec -- ai-push-hooks hook "$remote_name" "$remote_url" <"$push_stdin"
+   ```
+
+   Make the runner executable:
+
+   ```bash
+   chmod +x scripts/hooks/pre-push-runner.sh
+   ```
+
+4. Configure Lefthook to invoke only that runner in `lefthook.yml`:
 
    ```yaml
    pre-push:
      commands:
-       ai-push-hooks:
-         run: ai-push-hooks hook {1} {2}
+       repository-pre-push:
+         run: bash scripts/hooks/pre-push-runner.sh {1} {2}
+         use_stdin: true
    ```
 
-4. Push as usual. The workflow runs automatically before push completes.
+   `use_stdin: true` forwards Git's ref-update stream to the runner. The runner captures it before quality checks consume or close standard input, then replays it to `ai-push-hooks hook`. Lefthook's `{1}` and `{2}` are the remote name and remote URL. Keep all repository checks in this runner and keep the one `ai-push-hooks hook` call last so failures propagate and block the push.
+5. Configure modules and steps in [Configuration reference](#configuration-reference).
+6. Push as usual. The workflow runs automatically before push completes.
 
 ## Commands
 
+If installed as a local npm/pnpm dependency, run commands with `npx` or `pnpm exec`.
+
 | Command | What it does |
 | --- | --- |
 | `ai-push-hooks hook <remote-name> <remote-url>` | Runs the configured pre-push workflow. |
@@ -58,9 +106,7 @@ Requirements:
 
 ## Configuration overview
 
-- Config file lookup order: `ai-push-hooks.toml`, then `.ai-push-hooks.toml` (legacy).
-- If no config file is present, built-in defaults are used.
-- File values are deep-merged over defaults.
+- Config file: `ai-push-hooks.toml` in repo root (required).
 - Prompt resolution precedence for `llm` and `apply` steps:
   1. `prompt`
   2. `prompt_file`
@@ -72,11 +118,11 @@ Requirements:
 
 | Key | Type | Required | Default |
 | --- | --- | --- | --- |
-| `general` | table | no | built-in values |
-| `llm` | table | no | built-in values |
-| `logging` | table | no | built-in values |
-| `workflow` | table | yes | `{ modules = ["docs"] }` |
-| `modules` | table | yes | `{ docs = ... }` |
+| `general` | table | no | see section defaults |
+| `llm` | table | no | see section defaults |
+| `logging` | table | no | see section defaults |
+| `workflow` | table | yes | n/a |
+| `modules` | table | yes | n/a |
 
 ### `[general]`
 
@@ -86,13 +132,14 @@ Requirements:
 | `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.5"` | 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`). |
@@ -148,6 +195,8 @@ Requirements:
 
 `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
@@ -201,6 +250,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/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.5"
 variant = ""
 timeout_seconds = 800
 max_parallel = 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Modular AI push-hook workflow runner",
   "license": "MIT",
   "repository": {
@@ -11,7 +11,8 @@
     "ai-push-hooks": "bin/ai-push-hooks.js"
   },
   "scripts": {
-    "test": "uv run --with pytest pytest tests -q"
+    "test": "uv run --with pytest pytest tests -q",
+    "test:npm-pack": "node tests/npm-pack-smoke.mjs"
   },
   "files": [
     "bin",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.1.17"
+version = "0.1.19"
 description = "Modular AI push-hook workflow runner"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,6 +21,7 @@ classifiers = [
   "Programming Language :: Python :: 3.12",
   "Topic :: Software Development :: Version Control :: Git",
 ]
+dependencies = ["tomli>=2.0.0; python_version < '3.11'"]
 
 [project.scripts]
 ai-push-hooks = "ai_push_hooks.cli:main"

package/src/ai_push_hooks/artifacts.py

@@ -63,8 +63,11 @@ class ArtifactStore:
 
     def resolve_input(self, state: ModuleRuntimeState, reference: str) -> pathlib.Path:
         if ":" in reference:
-            module_and_step, artifact_name = reference.split("/", 1)
-            module_id, step_id = module_and_step.split(":", 1)
+            try:
+                module_and_step, artifact_name = reference.split("/", 1)
+                module_id, step_id = module_and_step.split(":", 1)
+            except ValueError as exc:
+                raise HookError(f"Invalid artifact reference: {reference}") from exc
             key = f"{module_id}:{step_id}/{artifact_name}"
         else:
             key = reference
@@ -72,6 +75,11 @@ class ArtifactStore:
         if path is None:
             path = state.artifacts.get(reference)
         if path is None:
+            if ":" in reference:
+                raise HookError(
+                    f"Unknown artifact reference: {reference}. Artifact references are module-local; "
+                    "use '<step>/<artifact>' from an earlier step in the same module."
+                )
             raise HookError(f"Unknown artifact reference: {reference}")
         return path
 

package/src/ai_push_hooks/cli.py

@@ -28,10 +28,8 @@ def init_config(template: str, force: bool, cwd: pathlib.Path | None = None) ->
         raise HookError("Only `minimal-docs` is supported")
     target_dir = cwd or pathlib.Path.cwd()
     config_path = target_dir / "ai-push-hooks.toml"
-    legacy_path = target_dir / ".ai-push-hooks.toml"
-    existing_path = config_path if config_path.exists() else legacy_path if legacy_path.exists() else None
-    if existing_path is not None and not force:
-        raise HookError(f"Refusing to overwrite existing config without --force: {existing_path}")
+    if config_path.exists() and not force:
+        raise HookError(f"Refusing to overwrite existing config without --force: {config_path}")
     config_path.write_text(MINIMAL_DOCS_TEMPLATE, encoding="utf-8")
     sys.stdout.write(str(config_path) + "\n")
     return 0

package/src/ai_push_hooks/config.py

@@ -1,189 +1,21 @@
 from __future__ import annotations
 
-import copy
-import json
 import os
 import pathlib
-import re
 from typing import Any
 
+from .executors.exec import env_bool
 from .prompts_builtin import BUILTIN_PROMPTS
 from .types import GeneralConfig, HookConfig, HookError, LlmConfig, LoggingConfig, ModuleConfig, StepConfig, SUPPORTED_STEP_TYPES, WorkflowConfig
-from .executors.exec import env_bool
 
 try:
     import tomllib
 except ModuleNotFoundError:  # pragma: no cover
-    tomllib = None  # type: ignore[assignment]
-
-DEFAULT_CONFIG_RAW: dict[str, Any] = {
-    "general": {
-        "enabled": True,
-        "allow_push_on_error": False,
-        "require_clean_worktree": False,
-        "skip_on_sync_branch": True,
-    },
-    "llm": {
-        "runner": "opencode",
-        "model": "openai/gpt-5.3-codex",
-        "variant": "",
-        "timeout_seconds": 800,
-        "max_parallel": 2,
-        "json_max_retries": 2,
-        "invalid_json_feedback_max_chars": 6000,
-        "json_retry_new_session": True,
-        "delete_session_after_run": True,
-        "max_diff_bytes": 180000,
-        "session_title_prefix": "ai-push-hooks",
-    },
-    "logging": {
-        "level": "status",
-        "jsonl": True,
-        "dir": ".git/ai-push-hooks/logs",
-        "capture_llm_transcript": True,
-        "transcript_dir": ".git/ai-push-hooks/transcripts",
-        "summary_dir": ".git/ai-push-hooks/summaries",
-        "print_llm_output": False,
-    },
-    "workflow": {"modules": ["docs"]},
-    "modules": {
-        "docs": {
-            "enabled": True,
-            "steps": [
-                {"id": "collect", "type": "collect", "collector": "docs_context"},
-                {
-                    "id": "query",
-                    "type": "llm",
-                    "inputs": ["collect/push.diff", "collect/changed-files.txt"],
-                    "output": "queries.json",
-                    "schema": "string_array",
-                    "fallback_prompt_id": "docs-query-basic",
-                },
-                {
-                    "id": "analyze",
-                    "type": "llm",
-                    "inputs": [
-                        "collect/push.diff",
-                        "collect/docs-context.txt",
-                        "query/queries.json",
-                        "collect/recent-commits.txt",
-                    ],
-                    "output": "issues.json",
-                    "schema": "docs_issue_array",
-                    "fallback_prompt_id": "docs-analysis-basic",
-                },
-                {
-                    "id": "apply",
-                    "type": "apply",
-                    "inputs": ["collect/push.diff", "collect/docs-context.txt", "analyze/issues.json"],
-                    "allow_paths": ["README.md", "docs/**/*.md"],
-                    "fallback_prompt_id": "docs-apply-basic",
-                },
-                {
-                    "id": "assert",
-                    "type": "assert",
-                    "inputs": ["apply/result.json"],
-                    "assertion": "docs_apply_requires_manual_commit",
-                },
-            ]
-        }
-    },
-}
+    import tomli as tomllib
 
 ALLOWED_TOP_LEVEL_KEYS = {"general", "llm", "logging", "workflow", "modules"}
 
 
-def _parse_multiline_string(lines: list[str], index: int, initial: str) -> tuple[str, int]:
-    chunks: list[str] = []
-    value = initial[3:]
-    while True:
-        end_index = value.find('"""')
-        if end_index >= 0:
-            chunks.append(value[:end_index])
-            return "\n".join(chunks), index
-        chunks.append(value)
-        index += 1
-        if index >= len(lines):
-            raise HookError("Unterminated multiline string in TOML fallback parser")
-        value = lines[index]
-
-
-def _assign_path(root: dict[str, Any], path: list[str], value: Any, array_mode: bool = False) -> dict[str, Any]:
-    current: Any = root
-    for part in path[:-1]:
-        if isinstance(current, list):
-            if not current:
-                current.append({})
-            current = current[-1]
-        current = current.setdefault(part, {})
-    key = path[-1]
-    if array_mode:
-        items = current.setdefault(key, [])
-        if not isinstance(items, list):
-            raise HookError(f"Invalid array-of-table path: {'.'.join(path)}")
-        item: dict[str, Any] = {}
-        items.append(item)
-        return item
-    current[key] = value
-    return current
-
-
-def _parse_scalar(raw: str) -> Any:
-    raw = raw.strip()
-    if raw.startswith('"') and raw.endswith('"'):
-        return raw[1:-1]
-    if raw in {"true", "false"}:
-        return raw == "true"
-    if re.fullmatch(r"-?\d+", raw):
-        return int(raw)
-    if raw.startswith("[") and raw.endswith("]"):
-        return json.loads(raw)
-    return raw
-
-
-def parse_toml_fallback(raw: str) -> dict[str, Any]:
-    parsed: dict[str, Any] = {}
-    lines = raw.splitlines()
-    current: Any = parsed
-    index = 0
-    while index < len(lines):
-        line = lines[index].strip()
-        index += 1
-        if not line or line.startswith("#"):
-            continue
-        if line.startswith("[[") and line.endswith("]]"):
-            path = [part.strip() for part in line[2:-2].split(".") if part.strip()]
-            current = _assign_path(parsed, path, None, array_mode=True)
-            continue
-        if line.startswith("[") and line.endswith("]"):
-            path = [part.strip() for part in line[1:-1].split(".") if part.strip()]
-            current = parsed
-            for part in path:
-                current = current.setdefault(part, {})
-            continue
-        if "=" not in line:
-            continue
-        key, value = line.split("=", 1)
-        key = key.strip()
-        value = value.strip()
-        if value.startswith('"""'):
-            parsed_value, index = _parse_multiline_string(lines, index - 1, value)
-        else:
-            parsed_value = _parse_scalar(value)
-        current[key] = parsed_value
-    return parsed
-
-
-def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
-    merged = copy.deepcopy(base)
-    for key, value in override.items():
-        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
-            merged[key] = deep_merge(merged[key], value)
-        else:
-            merged[key] = copy.deepcopy(value)
-    return merged
-
-
 def _normalize_step(raw: dict[str, Any]) -> StepConfig:
     step_type = str(raw.get("type", "")).strip()
     if step_type not in SUPPORTED_STEP_TYPES:
@@ -272,6 +104,7 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
             "allow_push_on_error": config.general.allow_push_on_error,
             "require_clean_worktree": config.general.require_clean_worktree,
             "skip_on_sync_branch": config.general.skip_on_sync_branch,
+            "base_branch": config.general.base_branch,
         },
         "llm": config.llm.__dict__.copy(),
         "logging": config.logging.__dict__.copy(),
@@ -296,6 +129,9 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     allow_dirty = env_bool("AI_PUSH_HOOKS_ALLOW_DIRTY")
     if allow_dirty is True:
         raw["general"]["require_clean_worktree"] = False
+    base_branch = os.getenv("AI_PUSH_HOOKS_BASE_BRANCH")
+    if base_branch:
+        raw["general"]["base_branch"] = base_branch.strip() or "main"
 
     logging_level = os.getenv("AI_PUSH_HOOKS_LOG_LEVEL")
     if logging_level:
@@ -315,19 +151,18 @@ def _apply_env_overrides(config: HookConfig) -> HookConfig:
     return _build_config(raw)
 
 
-def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path | None]:
-    config_path: pathlib.Path | None = None
-    raw = copy.deepcopy(DEFAULT_CONFIG_RAW)
-    for candidate in [repo_root / "ai-push-hooks.toml", repo_root / ".ai-push-hooks.toml"]:
-        if candidate.exists():
-            config_path = candidate
-            text = candidate.read_text(encoding="utf-8")
-            loaded = tomllib.loads(text) if tomllib is not None else parse_toml_fallback(text)
-            if not isinstance(loaded, dict):
-                raise HookError(f"Invalid config format in {candidate}")
-            raw = deep_merge(raw, loaded)
-            break
-    return _apply_env_overrides(_build_config(raw)), config_path
+def load_config(repo_root: pathlib.Path) -> tuple[HookConfig, pathlib.Path]:
+    config_path = repo_root / "ai-push-hooks.toml"
+    if not config_path.exists():
+        raise HookError(
+            "Missing required config file `ai-push-hooks.toml` in repo root. "
+            "Run `ai-push-hooks init --template minimal-docs` first"
+        )
+    text = config_path.read_text(encoding="utf-8")
+    loaded = tomllib.loads(text)
+    if not isinstance(loaded, dict):
+        raise HookError(f"Invalid config format in {config_path}")
+    return _apply_env_overrides(_build_config(loaded)), config_path
 
 
 def resolve_prompt_text(repo_root: pathlib.Path, step: StepConfig) -> str:

package/src/ai_push_hooks/executors/apply.py

@@ -8,6 +8,17 @@ from .exec import list_repo_changes, path_matches
 from .llm import call_opencode, finalize_opencode_session
 
 
+def _snapshot_file_contents(repo_root: pathlib.Path, paths: set[str]) -> dict[str, bytes | None]:
+    snapshot: dict[str, bytes | None] = {}
+    for path in paths:
+        full_path = repo_root / path
+        if full_path.is_file():
+            snapshot[path] = full_path.read_bytes()
+        else:
+            snapshot[path] = None
+    return snapshot
+
+
 def run_apply_step(
     context: RuntimeContext,
     state: ModuleRuntimeState,
@@ -23,6 +34,7 @@ def run_apply_step(
                 return {"changed": False, "changed_files": [], "skipped": True}
 
     baseline = list_repo_changes(context.repo_root)
+    baseline_contents = _snapshot_file_contents(context.repo_root, baseline)
     files = list(input_paths)
     agents = context.repo_root / "AGENTS.md"
     if agents.exists():
@@ -41,7 +53,14 @@ def run_apply_step(
         raise HookError(f"Apply step failed: {details}")
 
     after = list_repo_changes(context.repo_root)
-    changed_files = sorted(after - baseline)
+    newly_dirty = after - baseline
+    after_baseline_contents = _snapshot_file_contents(context.repo_root, baseline)
+    changed_while_dirty = {
+        path
+        for path, before_content in baseline_contents.items()
+        if before_content != after_baseline_contents[path]
+    }
+    changed_files = sorted(newly_dirty | changed_while_dirty)
     unexpected = [
         path for path in changed_files if not any(path_matches(path, pattern) for pattern in step.allow_paths)
     ]

package/src/ai_push_hooks/executors/exec.py

@@ -129,7 +129,7 @@ def path_matches(path: str, pattern: str) -> bool:
 
 def list_repo_changes(repo_root: pathlib.Path) -> set[str]:
     changes: set[str] = set()
-    output = git(repo_root, ["status", "--short"], check=False)
+    output = run_command(["git", "status", "--short"], cwd=repo_root).stdout
     for line in output.splitlines():
         payload = line[3:].strip()
         if payload:
@@ -141,7 +141,9 @@ def collect_ranges_from_stdin(
     repo_root: pathlib.Path,
     remote_name: str,
     stdin_lines: list[str],
+    base_branch: str = "main",
 ) -> list[str]:
+    base_branch = base_branch.strip() or "main"
     ranges: set[str] = set()
     for line in stdin_lines:
         parts = line.strip().split()
@@ -160,7 +162,7 @@ def collect_ranges_from_stdin(
                 ranges.add(f"{remote_sha}..{local_sha}")
         else:
             merge_base = git(
-                repo_root, ["merge-base", local_sha, f"{remote_name}/main"], check=False
+                repo_root, ["merge-base", local_sha, f"{remote_name}/{base_branch}"], check=False
             )
             if merge_base:
                 ranges.add(f"{merge_base}..{local_sha}")
@@ -438,7 +440,8 @@ def gh_pr_create_executor(
     if existing_pr:
         return {"skipped": False, "pr_url": existing_pr, "already_exists": True}
 
-    base_branch = str(payload.get("base_branch", "main")).strip() or "main"
+    default_base_branch = context.config.general.base_branch.strip() or "main"
+    base_branch = str(payload.get("base_branch", default_base_branch)).strip() or default_base_branch
     head_branch = str(payload.get("head_branch", branch_name)).strip() or branch_name
     title = sanitize_pr_title(str(payload.get("title", "")).strip(), branch_name)
     body = str(payload.get("body", "")).strip()

package/src/ai_push_hooks/executors/llm.py

@@ -32,7 +32,7 @@ def resolve_opencode_executable() -> str:
     cli_path = shutil.which("opencode-cli")
     if cli_path:
         return cli_path
-    raise HookError("opencode (or opencode-cli) is required but not installed")
+    raise HookError("opencode is required but not installed")
 
 
 def parse_opencode_json_run_output(raw: str) -> tuple[str | None, str]:

package/src/ai_push_hooks/hook.py

@@ -73,7 +73,9 @@ def run_hook(
             return 0
 
     actual_stdin = list(stdin_lines) if stdin_lines is not None else [line.rstrip("\n") for line in sys.stdin]
-    ranges = collect_ranges_from_stdin(repo_root, remote_name or "origin", actual_stdin)
+    ranges = collect_ranges_from_stdin(
+        repo_root, remote_name or "origin", actual_stdin, config.general.base_branch
+    )
     changed_files = collect_changed_files(repo_root, ranges) if ranges else []
     diff_text = collect_diff(repo_root, ranges, config.llm.max_diff_bytes) if ranges else ""
     run_id = generate_run_id()
@@ -104,6 +106,7 @@ def run_hook(
             "changed_files": changed_files,
             "diff_text": diff_text,
             "branch_name": current_branch(repo_root),
+            "base_branch": config.general.base_branch,
             "sync_branch": "beads-sync",
         },
     )

package/src/ai_push_hooks/modules/pr.py

@@ -14,6 +14,7 @@ from ..types import CollectorResult, RuntimeContext
 
 def collect_pr_context(context: RuntimeContext, state: Any) -> CollectorResult:
     branch_name = current_branch(context.repo_root)
+    base_branch = context.config.general.base_branch.strip() or "main"
     flag_env = ""
     for step in state.module.steps:
         if step.when_env:
@@ -25,7 +26,7 @@ def collect_pr_context(context: RuntimeContext, state: Any) -> CollectorResult:
             skip_module=True,
             skip_reason="PR create env flag is not enabled",
         )
-    if not branch_name or branch_name in {"HEAD", "main"} or not is_feature_branch(branch_name):
+    if not branch_name or branch_name in {"HEAD", base_branch} or not is_feature_branch(branch_name):
         return CollectorResult(
             artifacts={"pr-context.txt": f"branch={branch_name}\n"},
             skip_module=True,
@@ -61,7 +62,7 @@ def collect_pr_context(context: RuntimeContext, state: Any) -> CollectorResult:
             "pr-context.txt": "\n".join(
                 [
                     f"branch={branch_name}",
-                    f"base_branch=main",
+                    f"base_branch={base_branch}",
                     f"remote_name={context.remote_name or 'origin'}",
                 ]
             )

package/src/ai_push_hooks/prompts_builtin.py

@@ -64,10 +64,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.5"
 variant = ""
 timeout_seconds = 800
 max_parallel = 2

package/src/ai_push_hooks/types.py

@@ -23,12 +23,13 @@ class GeneralConfig:
     allow_push_on_error: bool = False
     require_clean_worktree: bool = False
     skip_on_sync_branch: bool = True
+    base_branch: str = "main"
 
 
 @dataclass(frozen=True)
 class LlmConfig:
     runner: str = "opencode"
-    model: str = "openai/gpt-5.3-codex"
+    model: str = "openai/gpt-5.5"
     variant: str = ""
     timeout_seconds: int = 800
     max_parallel: int = 2