project-init 0.3.0__py3-none-any.whl

project_init/templates/codex/dot_agents/skills/github_workflow/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: github_workflow
+description: Guides the agent through the full GitHub PR lifecycle — branch naming, push, review responses, and merge. Loaded automatically before any push, PR creation, review response, or merge action.
+when_to_use: Load before any push, PR creation, PR review response, merge, or release action — including when lifecycle scripts fail and a git/gh fallback is needed.
+user-invocable: false
+effort: high
+allowed-tools: Bash(git *) Bash(gh *) Bash(.claude/scripts/*) Read
+---
+
+Load this skill before any push, PR creation, review response, or merge action.
+
+## Quick reference
+
+| Step | Pattern |
+|------|---------|
+| Branch | `<type>/<PROJECT-KEY>-<n>-<kebab-slug>` e.g. `feat/PI-42-add-oauth` |
+| PR title | `type(PROJECT-123): description` e.g. `feat(PI-42): Add OAuth login` |
+| No-issue PR | `type: description` (no scope) e.g. `fix: Fix typo` |
+| PR body | Must include `Closes #N` (skip for no-issue PRs) |
+
+Commit messages use the same format (Conventional Commits). Legacy `[PROJECT-123][type]` is accepted by validators during transition but must not be emitted.
+
+Types: `feat` `fix` `chore` `docs` `test`
+
+## Standard lifecycle
+
+1. **Start work** — use the `start_task` skill. It runs `start_issue.sh` which creates
+   the branch, pushes, and opens a draft PR.
+   For minor no-issue work, use `.claude/scripts/create_nojira_pr.sh <type> "description"`.
+
+2. **Push during development:**
+   ```bash
+   .claude/scripts/push_branch.sh
+   ```
+   Never use bare `git push` — `push_branch.sh` retries transient GitHub errors.
+
+3. **Finish — push, mark ready, and merge:**
+   ```bash
+   .claude/scripts/finish_pr.sh [pr-number]
+   ```
+   `finish_pr.sh` pushes, marks the draft ready, runs `monitor_pr.sh --merge`,
+   and handles review cycles automatically.
+
+   Or run steps individually:
+   ```bash
+   .claude/scripts/push_branch.sh
+   .claude/scripts/promote_review.sh [pr-number]
+   .claude/scripts/monitor_pr.sh <pr-number> --merge
+   ```
+
+## Review cycle protocol
+
+`monitor_pr.sh --merge` exits **1** for CI or merge failures and **2** when
+`review/decision` fails while review cycles remain. Treat any non-zero exit as
+unfinished work: inspect the printed failure, fix or retry, then rerun the
+workflow. Do not report a PR as merged unless the script exits 0 after printing
+the merged or auto-merge-enabled status.
+
+1. Post a response for each review comment:
+   ```
+   gh pr comment <pr-number> --body "**Review response:**
+   - [comment]: Fixing — <reason>
+   - [comment]: Not applying — <reason>"
+   ```
+2. Fix actionable code, then push: `.claude/scripts/push_branch.sh`
+3. Re-run with the next cycle number:
+   ```bash
+   .claude/scripts/monitor_pr.sh <pr-number> --merge --review-cycle <N>
+   ```
+4. After 1 review-fix cycle, the script auto force-merges with `--admin`.
+
+**Before applying any comment:** read the current file state. Check whether the
+comment is stale (already fixed), contradicts conventions, or is correct. Never
+blindly apply a suggestion — post reasoning even when rejecting.
+
+## Issue titles vs PR titles
+
+- **Issue titles**: plain description only — type is carried by the label.
+- **PR titles**: must include `[type]` — PR titles become merge commit messages in `git log`.
+- **nojira**: for minor fixes without a tracking issue; no `Closes #N` needed.

project_init/templates/codex/dot_agents/skills/request_review/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: request_review
+description: Mark the current draft PR ready for review
+when_to_use: Use when a draft PR is ready to move from Draft to In Review status. Marks the PR ready and triggers board automation.
+argument-hint: "[pr-number]"
+allowed-tools: Bash Read
+---
+
+Mark PR $ARGUMENTS (or current branch's PR if omitted) ready for review.
+
+## Steps
+
+1. **Promote to ready**:
+   ```bash
+   .claude/scripts/promote_review.sh $ARGUMENTS
+   ```
+   `board-automation.yml` moves the board card to **In Review** automatically.
+
+2. **Next steps**: Reviewers will be pinged. When they request changes, they'll post comments on the PR.

project_init/templates/codex/dot_agents/skills/review/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: review
+description: Review staged or recent changes for bugs, style issues, and missed edge cases
+when_to_use: Use when you want a code review of work — staged changes, a specific commit, or a commit range.
+argument-hint: "[commit-range or file]"
+allowed-tools: Bash Read Grep Glob
+---
+
+Review the code changes specified by: $ARGUMENTS
+
+If no argument given, review all staged changes (`git diff --cached`). If nothing is staged, review the last commit.
+
+Focus on:
+- **Bugs** — logic errors, off-by-ones, null/undefined risks
+- **Security** — injection, auth issues, secret exposure
+- **Style** — naming, dead code, overly complex logic
+- **Edge cases** — empty inputs, concurrency, error paths

project_init/templates/codex/dot_agents/skills/save_memory/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: save_memory
+description: Save a fact to project memory for future sessions
+when_to_use: Use when you learn something important that should persist across conversations — a decision, a constraint, a pattern, or an external reference.
+argument-hint: "<fact to remember>"
+allowed-tools: Read Write Glob
+---
+
+Save this to project memory: $ARGUMENTS
+
+Follow the memory convention in `.claude/memory/README.md`:
+
+1. Decide the memory type (user / feedback / project / reference)
+2. Choose a descriptive filename (e.g., `feedback_testing.md`, `project_deadline.md`)
+3. Check if an existing memory file already covers this — update it instead of duplicating
+4. Write the file with proper frontmatter (name, description, type)
+5. Add a one-line entry to `.claude/memory/MEMORY.md`

project_init/templates/codex/dot_agents/skills/session_summary/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: session_summary
+description: Summarizes the current session and saves it to the vault. Use at the end of a work session to record completed work, decisions made, and open items for the next session.
+when_to_use: Use when the user says "save the session", "wrap up", "summarize what we did", or at the end of a long work session.
+effort: medium
+allowed-tools: Bash(git *) Read Write Glob Grep
+---
+
+Summarize this session and save it to the vault:
+
+1. **Gather context**:
+   - Run `git log --since='2 hours ago' --oneline` for recent commits
+   - Run `git diff --stat` for uncommitted changes
+   - Review the conversation for key decisions and discoveries
+
+2. **Write the summary** to `.claude/vault/sessions/` with today's date:
+   ```
+   # Session YYYY-MM-DD (manual)
+
+   ## What was done
+   - (bullet list of completed work)
+
+   ## Decisions made
+   - (any architectural or approach decisions, with reasoning)
+
+   ## Open items
+   - (anything left unfinished or discovered but not addressed)
+
+   ## Notes
+   - (anything else worth remembering)
+   ```
+
+3. **Update memory** if any reusable facts emerged (write to the project memory directory)
+
+Keep the summary concise — a future agent should be able to skim it in 30 seconds.

project_init/templates/codex/dot_agents/skills/start_task/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: start_task
+description: Creates a GitHub Issue, branch, and draft PR before implementation begins. Use before any non-trivial task to keep work traceable — one issue, one branch, one PR.
+when_to_use: Use when the user says "start work on X", "create a ticket for Y", or "begin a new task". Do not use for trivial one-off changes that don't need tracking.
+argument-hint: "[task title]"
+allowed-tools: Bash(gh *) Bash(git *) Read
+---
+
+Before starting any non-trivial task, create a GitHub Issue, a dedicated branch, and a draft PR. This keeps work traceable and every PR maps to exactly one issue.
+
+## Mandatory scripts
+
+| Action | Script | Never use |
+|--------|--------|-----------|
+| Start issue + branch + draft PR | `.claude/scripts/start_issue.sh <n> <type>` | bare `git checkout -b` + bare `gh pr create` |
+| Push branch | `.claude/scripts/push_branch.sh` | bare `git push` |
+| **Push + promote + merge (all-in-one)** | `.claude/scripts/finish_pr.sh <n>` | `gh pr ready`, bare `gh pr merge`, `gh pr checks --watch` |
+
+## Steps
+
+1. **Clarify scope** — if $ARGUMENTS is empty or vague, ask the user for:
+   - Task title (one line, imperative: "Add X", "Fix Y", "Refactor Z")
+   - Work type: `feat` / `fix` / `chore` / `docs` / `test`
+
+2. **Check for existing issue and PR** — run `gh issue list` and `gh pr list`. If an issue already exists, use its number. If a draft PR already exists for that issue, use it — do **not** create a second PR. Skip to step 5.
+
+3. **Create the issue** — load the `create_issue` skill and follow it. It gathers priority, area, size, references, dependencies, and acceptance criteria before running:
+   ```bash
+   ISSUE_NUMBER=$(.claude/scripts/create_issue.sh <type> "<title>" --priority <priority> --area "<area>" --size <size> --acceptance "<criterion>")
+   echo "Created issue #$ISSUE_NUMBER"
+   ```
+
+4. **Start work** — create the branch, push, and open a draft PR:
+   ```bash
+   .claude/scripts/start_issue.sh <issue-number> <type>
+   ```
+   This derives the branch name (`<issue_type>/<project_abbr>-<issue_number>-<slug>`) from the issue title, pushes it, and opens a draft PR with the correct `[PROJECT-123][type]` title and `Closes #n` body.
+
+5. **Proceed** — only begin implementation after the scripts have run successfully.
+
+6. **When ready to merge** — load the `github_workflow` skill for the
+   full push → promote → monitor/merge lifecycle and review-cycle protocol.
+
+## Rules
+
+- Every non-trivial task must have a GitHub Issue, a branch, and a draft PR — all before the first line of implementation code.
+- One issue → one branch → one PR.
+- `board-automation.yml` moves the board card to **In Progress** automatically when the PR is opened. No manual board move needed.

project_init/templates/codex/dot_agents/skills/status/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: status
+description: Show project status — git state, recent commits, open tasks, and memory summary
+when_to_use: Use when you want a quick snapshot of the project — current branch, uncommitted changes, recent work, active memory, and open TODOs.
+allowed-tools: Bash Read Grep Glob
+---
+
+Give me a concise project status report:
+
+1. **Git state** — current branch, uncommitted changes, commits ahead/behind remote
+2. **Recent work** — last 5 commits (one line each)
+3. **Memory** — read `.claude/memory/MEMORY.md` and list the key facts
+4. **Open items** — scan for TODO/FIXME/HACK in the codebase (top 10)
+
+Keep the report under 30 lines. Use markdown formatting.

project_init/templates/codex/dot_codex/hooks.json.tmpl

@@ -0,0 +1,17 @@
+{{#if codex}}{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/agent_guard_adapter.py codex",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+{{/if codex}}

project_init/templates/fallback/dot_claude/hooks/github_command_guard.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# github_command_guard.sh — delegate to dag_workflow.py guard.
+# PreToolUse hook on Bash. Receives tool input JSON on stdin.
+#
+# All command-pattern matching, redirect rules, and DAG prerequisite checks
+# live in dag_workflow.py next to this script. Adding a new banned command
+# means editing COMMAND_RULES there, not this file.
+
+set -euo pipefail
+
+exec python3 "$(dirname "$0")/dag_workflow.py" guard

project_init/templates/fallback/dot_claude/hooks/post_edit_lint.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# post_edit_lint.sh — runs linter on edited files after Edit/Write/MultiEdit.
+# Invoked by Claude Code's PostToolUse hook.
+# Outputs additionalContext JSON if unfixable lint errors remain so Claude
+# self-corrects in the same turn.
+
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+INPUT=$(cat)
+
+FILE=$(printf '%s' "$INPUT" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+ti = d.get('tool_input', {}) or {}
+print(ti.get('file_path') or ti.get('filePath') or '')
+" 2>/dev/null || true)
+
+[ -z "$FILE" ] && exit 0
+[ ! -f "$FILE" ] && exit 0
+
+ERRORS=""
+
+case "$FILE" in
+    *.py)
+        # Prefer 'uv run ruff' inside a uv-managed project so the hook uses
+        # the same ruff the project itself uses; fall back to a system ruff.
+        if { [ -f "$ROOT/pyproject.toml" ] || [ -f "$ROOT/uv.lock" ]; } && command -v uv &>/dev/null; then
+            uv run ruff check --fix --quiet "$FILE" 2>/dev/null || true
+            uv run ruff format --quiet "$FILE" 2>/dev/null || true
+            ERRORS=$(uv run ruff check --quiet "$FILE" 2>&1 || true)
+        elif command -v ruff &>/dev/null; then
+            ruff check --fix --quiet "$FILE" 2>/dev/null || true
+            ruff format --quiet "$FILE" 2>/dev/null || true
+            ERRORS=$(ruff check --quiet "$FILE" 2>&1 || true)
+        fi
+        ;;
+    *.js|*.ts|*.jsx|*.tsx)
+        # Use bunx (bun's package runner) — consistent with project convention (PI-15).
+        if command -v bunx &>/dev/null; then
+            bunx eslint --fix --quiet "$FILE" 2>/dev/null || true
+            ERRORS=$(bunx eslint --quiet "$FILE" 2>&1 || true)
+        fi
+        ;;
+esac
+
+if [ -n "$ERRORS" ]; then
+    python3 -c "
+import json, sys
+file, errors = sys.argv[1], sys.argv[2]
+print(json.dumps({'additionalContext': f'Lint errors in {file} (after auto-fix attempt) — please fix before continuing:\n{errors}'}))
+" "$FILE" "$ERRORS"
+fi
+
+exit 0

project_init/templates/fallback/dot_claude/hooks/pre_commit_gate.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# pre_commit_gate.sh — blocks git commit if staged files fail linting.
+# PreToolUse hook on Bash. Receives tool input JSON on stdin.
+# Auto-fixes what it can and re-stages; blocks only if errors remain.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+CMD=$(printf '%s' "$INPUT" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+print((d.get('tool_input', {}) or {}).get('command', '') or '')
+" 2>/dev/null || true)
+
+# Only intercept git commit commands
+case "$CMD" in
+    *"git commit"*) ;;
+    *) exit 0 ;;
+esac
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+ERRORS=""
+
+# Lint and auto-fix staged Python files. Prefer 'uv run ruff' inside a
+# uv-managed project so the hook uses the same ruff the project itself uses;
+# fall back to a system ruff binary.
+mapfile -t STAGED_PY < <(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep '\.py$' || true)
+if [ "${#STAGED_PY[@]}" -gt 0 ]; then
+    LINT_OUT=""
+    if { [ -f "$ROOT/pyproject.toml" ] || [ -f "$ROOT/uv.lock" ]; } && command -v uv &>/dev/null; then
+        uv run ruff check --fix --quiet "${STAGED_PY[@]}" 2>/dev/null || true
+        uv run ruff format --quiet "${STAGED_PY[@]}" 2>/dev/null || true
+        LINT_OUT=$(uv run ruff check --quiet "${STAGED_PY[@]}" 2>&1 || true)
+    elif command -v ruff &>/dev/null; then
+        ruff check --fix --quiet "${STAGED_PY[@]}" 2>/dev/null || true
+        ruff format --quiet "${STAGED_PY[@]}" 2>/dev/null || true
+        LINT_OUT=$(ruff check --quiet "${STAGED_PY[@]}" 2>&1 || true)
+    fi
+    if [ -n "$LINT_OUT" ]; then
+        ERRORS="${ERRORS}Python lint errors:\n${LINT_OUT}\n"
+    fi
+    # Re-stage auto-fixed files so the commit includes the fixes
+    git add "${STAGED_PY[@]}" 2>/dev/null || true
+fi
+
+# Lint and auto-fix staged JS/TS files
+# Use bunx (bun's package runner) — consistent with project convention (PI-15).
+mapfile -t STAGED_JS < <(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\.(js|ts|jsx|tsx)$' || true)
+if [ "${#STAGED_JS[@]}" -gt 0 ] && command -v bunx &>/dev/null; then
+    bunx eslint --fix --quiet "${STAGED_JS[@]}" 2>/dev/null || true
+    LINT_OUT=$(bunx eslint --quiet "${STAGED_JS[@]}" 2>&1 || true)
+    if [ -n "$LINT_OUT" ]; then
+        ERRORS="${ERRORS}JS/TS lint errors:\n${LINT_OUT}\n"
+    fi
+    git add "${STAGED_JS[@]}" 2>/dev/null || true
+fi
+
+# PI-139: when the project ships a justfile with a lint recipe and just is
+# installed, additionally gate on `just lint` — the same definition of "lint
+# passes" CI and every agent use. Per-file findings above are preserved: the
+# recipe is language-specific, so in a mixed repo it may not cover everything
+# the per-file checks caught (a passing recipe must not wash those out).
+if command -v just >/dev/null 2>&1 && [ -f "$ROOT/justfile" ] \
+   && (cd "$ROOT" && just --show lint >/dev/null 2>&1); then
+    JUST_OUT=$(cd "$ROOT" && just lint 2>&1) || ERRORS="${ERRORS}Lint errors (just lint):\n${JUST_OUT}\n"
+fi
+
+if [ -n "$ERRORS" ]; then
+    python3 -c "
+import json, sys
+errors = sys.argv[1].replace('\\\\n', '\n')
+msg = 'Pre-commit lint check failed. Fix these errors before committing:\n\n' + errors
+print(json.dumps({'decision': 'block', 'reason': msg}))
+" "$ERRORS"
+fi
+
+exit 0

project_init/templates/fallback/dot_claude/hooks/prod_guard.py

@@ -0,0 +1,140 @@
+"""Prod-safety guard (PI-168, ADR-012): deny destructive infra/DB commands.
+
+PreToolUse hook on Bash. Deterministic deny-table — no LLM, no network.
+Destructive operations that bypass the git/CI boundary (cloud deletes,
+DROP DATABASE, terraform destroy, …) get:
+
+- ``ask``   in interactive sessions — a human confirms or rejects;
+- ``block`` in fully autonomous sessions (``bypassPermissions``) — there is
+  no human to ask, so the command is blocked outright.
+
+Escape hatch: ``safety.allow`` in ``.claude/config.yaml`` holds a JSON list
+of regex patterns; a command matching any of them is never flagged. Use it
+for known-safe contexts (e.g. a dev-cluster kubectl context).
+
+This is a guardrail, not the security boundary (ADR-007/ADR-012): a
+sufficiently creative command can evade a deny-list. The guarantee comes
+from credential separation — agent sessions must never hold production
+credentials (see .claude/docs/guides/secrets.md).
+
+Fail-open by design: any internal error lets the command proceed.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+# (pattern, label) — matched against the full command string. ``_SEG``
+# tolerates global flags between the CLI name and the destructive verb
+# (e.g. `kubectl --context prod delete …`) while stopping at pipeline and
+# command separators; the cost is rare false positives on odd resource
+# names, which the ask/allowlist paths absorb cheaply.
+_SEG = r"[^|;&]*?"
+DENY_RULES: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"\bterraform\s+(destroy|apply\s+.*-destroy)\b"), "terraform destroy"),
+    (re.compile(rf"\bkubectl\b{_SEG}\bdelete\b"), "kubectl delete"),
+    (re.compile(rf"\bhelm\b{_SEG}\b(uninstall|delete)\b"), "helm uninstall"),
+    (re.compile(rf"\baws\b{_SEG}\b(delete|terminate|remove)\S*\b"), "aws delete/terminate"),
+    (re.compile(rf"\baws\b{_SEG}\bs3\s+(rb\b|rm\b{_SEG}--recursive)"), "aws s3 bucket/recursive removal"),
+    (re.compile(rf"\bgcloud\b{_SEG}\bdelete\b"), "gcloud delete"),
+    (re.compile(rf"\baz\b{_SEG}\bdelete\b"), "az delete"),
+    (re.compile(r"\bdrop\s+(table|database|schema)\b", re.IGNORECASE), "SQL DROP"),
+    (re.compile(r"\btruncate\s+table\b", re.IGNORECASE), "SQL TRUNCATE"),
+    (re.compile(r"\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)[a-zA-Z]*\s+(/(?!tmp\b)|~)"),
+     "recursive force-remove outside the project"),
+    (re.compile(r"\bgh\s+repo\s+delete\b"), "gh repo delete"),
+    (re.compile(r"\bdocker\s+(volume\s+prune|system\s+prune)\b"), "docker prune"),
+]
+
+# Fully autonomous mode: no human is watching the prompt, so "ask" is
+# meaningless — block outright. Other modes (default, plan, acceptEdits)
+# still surface an interactive permission prompt for Bash.
+_AUTONOMOUS_MODES = {"bypassPermissions", "dangerouslySkipPermissions"}
+
+
+def _find_config(start: Path) -> Path | None:
+    """Walk up from *start* to the project's .claude/config.yaml, if any."""
+    for candidate in (start, *start.parents):
+        config = candidate / ".claude" / "config.yaml"
+        if config.is_file():
+            return config
+    return None
+
+
+def _allow_patterns(root: Path) -> list[re.Pattern[str]]:
+    """Read the safety.allow JSON list from .claude/config.yaml (fail-open).
+
+    *root* is the Bash tool's cwd, which may be a subdirectory after `cd` —
+    the config is located by walking up the tree.
+    """
+    config = _find_config(root)
+    if config is None:
+        return []
+    try:
+        in_safety = False
+        for line in config.read_text(encoding="utf-8").splitlines():
+            if line.startswith("safety:"):
+                in_safety = True
+                continue
+            if in_safety:
+                if line.strip() and not line.startswith(" "):
+                    break
+                stripped = line.strip()
+                if stripped.startswith("allow:"):
+                    raw = stripped.split(":", 1)[1].strip()
+                    return [re.compile(p) for p in json.loads(raw)]
+    except (OSError, json.JSONDecodeError, re.error):
+        pass
+    return []
+
+
+def evaluate(command: str, permission_mode: str, allow: list[re.Pattern[str]]) -> dict | None:
+    """Return the hook verdict for *command*, or None to let it through."""
+    if any(p.search(command) for p in allow):
+        return None
+    for pattern, label in DENY_RULES:
+        if pattern.search(command):
+            reason = (
+                f"prod_guard: '{label}' is a destructive operation. "
+                "If this is intentional and safe, add a matching regex to "
+                "safety.allow in .claude/config.yaml, or run it yourself. "
+                "(Guardrail only — real protection is credential separation, "
+                "see .claude/docs/guides/secrets.md.)"
+            )
+            if permission_mode in _AUTONOMOUS_MODES:
+                return {"decision": "block", "reason": reason}
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "ask",
+                    "permissionDecisionReason": reason,
+                }
+            }
+    return None
+
+
+def main() -> int:
+    """Read the PreToolUse payload from stdin; print a verdict if any."""
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+    except json.JSONDecodeError:
+        return 0
+    command = ((payload.get("tool_input") or {}).get("command") or "").strip()
+    if not command:
+        return 0
+    mode = payload.get("permission_mode") or payload.get("permissionMode") or ""
+    root = Path(payload.get("cwd") or ".")
+    try:
+        verdict = evaluate(command, mode, _allow_patterns(root))
+    except Exception:  # noqa: BLE001 — guardrail must never break the session
+        return 0
+    if verdict is not None:
+        sys.stdout.write(json.dumps(verdict))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

project_init/templates/fallback/dot_claude/hooks/session_setup.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# SessionStart bootstrap (PI-146): make a fresh/remote container immediately
+# usable — sync dependencies so tests and linters run instead of failing on
+# a missing venv. Fast on warm environments: a content stamp of the
+# dependency manifests short-circuits before any tool runs.
+set -uo pipefail # not -e: a failed bootstrap must never break the session
+
+ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+cd "$ROOT" || exit 0
+STAMP=".claude/.session_setup_stamp"
+LOG=".claude/logs/session_setup.log"
+mkdir -p .claude/logs
+
+fingerprint() {
+  cat pyproject.toml uv.lock package.json bun.lock bun.lockb go.mod go.sum 2>/dev/null \
+    | sha256sum | cut -d' ' -f1
+}
+
+# The stamp alone is not enough: an ephemeral container can restore the repo
+# (stamp included) without the synced environment, so check for it too.
+env_present() {
+  { [ ! -f pyproject.toml ] || [ -d .venv ]; } \
+    && { [ ! -f package.json ] || [ -d node_modules ]; }
+}
+
+CURRENT="$(fingerprint)"
+if [ -f "$STAMP" ] && [ "$(cat "$STAMP" 2>/dev/null)" = "$CURRENT" ] && env_present; then
+  exit 0 # warm environment — nothing to do
+fi
+
+bootstrap() {
+  # Prefer the justfile setup recipe — the canonical bootstrap entry point.
+  if command -v just >/dev/null 2>&1 && [ -f justfile ] \
+    && just --show setup >/dev/null 2>&1; then
+    just setup
+  elif [ -f pyproject.toml ] && command -v uv >/dev/null 2>&1; then
+    uv sync --extra dev 2>/dev/null || uv sync
+  elif [ -f package.json ] && command -v bun >/dev/null 2>&1; then
+    bun install
+  elif [ -f go.mod ] && command -v go >/dev/null 2>&1; then
+    go mod download
+  else
+    return 2 # nothing recognized to set up
+  fi
+}
+
+bootstrap >"$LOG" 2>&1
+case $? in
+0)
+  echo "$CURRENT" >"$STAMP"
+  echo "session_setup: dependencies synced for fresh environment"
+  ;;
+2)
+  # No manifest/tool to bootstrap: stamp silently so later sessions skip
+  # the probe, but claim nothing — no sync happened.
+  echo "$CURRENT" >"$STAMP"
+  ;;
+*)
+  echo "session_setup: bootstrap failed — see $LOG" >&2
+  ;;
+esac
+exit 0