create-ai-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ram Christopher Baarde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,340 @@
+<div align="center">
+
+# ai-memory
+
+**Persistent, agent-agnostic session memory for AI coding CLIs. One Markdown vault, any agent.**
+
+Give Claude Code, Codex, Gemini, Cursor, and opencode a shared second brain that
+survives across sessions: durable profile, per-project context, and last-session carryover,
+injected at launch. The vault is the source of truth; the chat is disposable.
+
+No daemon, no database, no API key. Just zsh and Markdown files you can read.
+
+![zsh](https://img.shields.io/badge/shell-zsh-89e051)
+![tests](https://img.shields.io/badge/tests-35%20passing-brightgreen)
+![license](https://img.shields.io/badge/license-MIT-blue)
+![PRs](https://img.shields.io/badge/PRs-welcome-orange)
+
+</div>
+
+---
+
+## The problem
+
+Every AI coding session starts from zero.
+
+Claude Code, Codex, Gemini CLI. The moment a session ends, the agent forgets what
+was built, the decisions that were made, the PRD, every architectural and codebase
+choice. The context that mattered most evaporates with the chat thread, and the
+next run begins blind.
+
+You pay the same tax on every run:
+
+- **Agent amnesia.** Accumulated project knowledge vanishes when the thread closes.
+- **Lost decisions.** Why a choice was made is nowhere; the next run re-litigates it.
+- **Reload overhead.** You re-explain the stack, constraints, and conventions from scratch.
+- **No continuity.** Nothing carries "where I left off" into the next session.
+
+Switching agents makes it worse. Each CLI is its own island with its own memory,
+or none. Knowledge earned in Claude doesn't reach Codex.
+
+## How it works
+
+Keep the memory outside the chat, in plain Markdown on disk, and inject it into
+whichever agent you launch. Because it's just files, the vault doubles as an
+[Obsidian](https://obsidian.md) folder with graph view, backlinks, and search;
+nothing here requires Obsidian.
+
+Memory sits in three layers, each injected at the right scope:
+
+| Layer | Lives in | Injected | Holds |
+|---|---|---|---|
+| **Global** | `_Global_Profile.md`, `_Standards.md` | every session, every project | who you are, your rules, coding standards, commit policy |
+| **Project** | `_projects/<repo>.md` | sessions in that repo | purpose, architecture, constraints, active decisions |
+| **Session** | `_session_logs/<repo>/<timestamp>.md` | next session as carryover | what changed, blockers, next steps |
+
+```
+  $ claude-start
+        │
+        ├─ resolve project from the current git repo
+        ├─ create a fresh session log from the template
+        ├─ gather:  Global Profile + Standards         (who you are)
+        │           Project note                        (this repo)
+        │           latest prior session log            (where you left off)
+        ├─ ask which session skills to enable           (optional)
+        └─ launch the agent with all of it as the first prompt
+              │
+              ▼
+        …you work…
+              │
+              ▼
+        on exit, a hook writes an auto session log
+        (branch, commits made, uncommitted changes)
+        → the NEXT session inherits it as carryover
+```
+
+One environment variable, `AI_MEM_ROOT`, points at the vault, so the system moves
+between machines by pointing at the same folder.
+
+## A session, start to finish
+
+```console
+$ cd ~/code/checkout-api
+$ claude-start
+  Use terse output this session? [y/N] n
+
+  # Claude launches pre-loaded with:
+  #   • your profile + coding standards + commit policy   (global)
+  #   • checkout-api: purpose, architecture, decisions    (project)
+  #   • "Next: wire the refund webhook"                   (last session's carryover)
+
+… you build the refund webhook, make a few commits …
+
+$ ai-note "refund webhook live; still need idempotency keys"   # jot mid-session
+
+# On exit, a hook stamps the session log with the branch, the commits you made,
+# and anything uncommitted. Tomorrow's claude-start picks up exactly there.
+```
+
+No copy-pasting context. No re-explaining the stack. No "where were we."
+
+## Quickstart
+
+```sh
+npm create ai-memory@latest     # copies the tool in and runs the setup, no git clone
+exec zsh
+```
+
+Then, from inside any git repo:
+
+```sh
+claude-start                    # or codex-start / gemini-start / cursor-start / opencode-start
+```
+
+The agent opens already knowing your standards, this project, and where you left
+off last time.
+
+## Table of contents
+
+<table>
+<tr>
+<td valign="top" width="33%">
+
+**Overview**
+
+- [The problem](#the-problem)
+- [How it works](#how-it-works)
+- [A session, start to finish](#a-session-start-to-finish)
+
+**Getting started**
+
+- [Quickstart](#quickstart)
+- [Install](#install)
+- [Commands](#commands)
+
+</td>
+<td valign="top" width="33%">
+
+**Reference**
+
+- [Session skills](#session-skills-optional)
+- [Vault layout](#vault-layout)
+- [Adding a new agent](#adding-a-new-agent)
+- [Optional integrations](#optional-integrations)
+- [Configuration](#configuration)
+
+</td>
+<td valign="top" width="33%">
+
+**Project**
+
+- [Tests](#tests)
+- [Design notes](#design-notes)
+- [Roadmap](#roadmap)
+- [License](#license)
+
+</td>
+</tr>
+</table>
+
+## Install
+
+Pick whichever fits how you manage your shell. All paths end at the same place.
+
+**npm** (no git clone; the tool is bundled in the package):
+
+```sh
+npm create ai-memory@latest         # into ~/ai-memory, then runs the setup
+npx create-ai-memory ~/code/ai-memory   # or a directory you choose
+```
+
+**zsh plugin manager:**
+
+```zsh
+# zinit
+zinit light rambaarde/create-ai-memory
+
+# antidote (in your plugins file)
+rambaarde/create-ai-memory
+
+# oh-my-zsh: clone into custom/plugins, then add create-ai-memory to plugins=(...)
+```
+
+Plugin-manager installs only source the module. That's fine: the vault
+auto-scaffolds from the shipped templates on first use, so `install.sh` is
+optional. Set `AI_MEM_ROOT` in `~/.zshrc` first if you don't want the default
+`~/.ai-memory/_Ai_Memory`.
+
+**Clone and run** (the source of truth all paths reuse):
+
+```sh
+git clone https://github.com/rambaarde/create-ai-memory.git ~/ai-memory
+~/ai-memory/install.sh
+```
+
+> **zsh only.** The module uses `print -r`, `${(s:|:)}`, and `select`. A bash
+> port is welcome as a PR; see [Roadmap](#roadmap).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `claude-start` · `codex-start` · `gemini-start` · `cursor-start` · `opencode-start` | Launch an agent with full vault context and the session-skill picker |
+| `ai-start [project]` | Prepare the session (project note and fresh log) without launching an agent |
+| `ai-context [project]` | Print the vault context block for the current repo, and arm the git commit guard |
+| `ai-note <text>` | Append a timestamped note to today's session log while you work |
+
+Project is auto-resolved from the current git repo; pass a name to override.
+
+## Session skills (optional)
+
+You define your own per-session skills; ai-memory ships none. At launch it asks
+y/n for each skill you registered, then injects the chosen instruction blocks into
+the agent (and for Cursor, writes them as a managed always-apply rule). Register
+nothing and every session is plain.
+
+Add skills in `~/.zshrc` before sourcing the module. Each entry maps a `key` to
+`prompt::instruction block`, and `AI_MEM_SKILL_ORDER` sets the ask order:
+
+```zsh
+typeset -gA AI_MEM_SKILLS
+AI_MEM_SKILLS[terse]='Use terse output this session?::Respond tersely; drop filler and hedging.'
+AI_MEM_SKILLS[design]='Use strict UI design discipline?::Apply careful frontend/UI design review to any design work.'
+AI_MEM_SKILL_ORDER=(terse design)
+
+source "$HOME/ai-memory/shell/ai-mem.zsh"
+```
+
+The injected block applies for the whole run, so a session's chosen skills persist
+as instructions across every change the agent makes.
+
+## Vault layout
+
+```
+$AI_MEM_ROOT/
+  _Global_Profile.md          your cross-project rules      (injected every session)
+  _Standards.md               extra shared standards        (injected every session)
+  _projects/
+    _project_template.md       scaffold for new project notes
+    <repo>.md                  per-project durable context
+  _session_logs/
+    _session_template.md       scaffold for new session logs
+    <repo>/
+      <repo>-<timestamp>.md    one file per session
+```
+
+Notes are created from templates on first use and never overwritten. Edit
+`_Global_Profile.md` and `_Standards.md` to make them yours; the shipped versions
+are sanitized placeholders.
+
+## Adding a new agent
+
+Launchers aren't hardcoded. Each agent is one small adapter, and the
+`<name>-start` function is generated for you. `claude`, `codex`, `gemini`,
+`cursor`, and `opencode` ship built in. To add another, say `aider`:
+
+1. Define the adapter in `shell/adapters.zsh`. It receives `$1` memory prompt,
+   `$2` mode block, and `$3` onward extra args:
+   ```zsh
+   _ai_adapter_aider() {
+       local memory_prompt="$1"
+       aider --message "$memory_prompt"
+   }
+   ```
+2. Register it in `~/.zshrc` before sourcing, or edit the default:
+   ```zsh
+   export AI_MEM_AGENTS="claude codex gemini cursor opencode aider"
+   ```
+3. `aider-start` now exists. No core edits.
+
+## Optional integrations
+
+### Claude Code hooks
+The files live in `hooks/claude/`. Record repo `HEAD` at session start, then on
+exit write an auto block to the log with the branch, commits made this session, and
+uncommitted changes, so the next session has real carryover instead of an empty
+template. Merge `settings.snippet.json` into `~/.claude/settings.json`, replacing
+`<AI_MEM_HOME>` with an absolute path. Both hooks no-op for plain `claude` runs;
+they gate on `$AI_MEM_ACTIVE_SESSION_LOG`.
+
+### Git commit guard
+The files live in `hooks/git/`:
+
+- **`commit-msg`** requires Conventional Commits and a structured body, and that
+  `ai-context` was loaded in the committing shell, matching a per-repo token. An
+  agent can't commit without the vault context loaded.
+- **`pre-push`** blocks direct pushes to `main` unless `ALLOW_PUSH_TO_MAIN=1`.
+
+Enable per repo:
+
+```sh
+cp ~/ai-memory/hooks/git/* <repo>/.githooks/
+git -C <repo> config core.hooksPath .githooks
+```
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `AI_MEM_ROOT` | `$HOME/.ai-memory/_Ai_Memory` | Vault root. Point at any folder, including an existing Obsidian vault |
+| `AI_MEM_AGENTS` | `claude codex gemini cursor opencode` | Space-separated agents to generate `-start` functions for |
+| `AI_MEM_SKILLS` / `AI_MEM_SKILL_ORDER` | empty | Your per-session skills (see above) |
+
+## Tests
+
+Offline unit suite (throwaway vault + git repo, no network): path guarding,
+project resolution, session prep, context prompt, skill picker, launcher
+generation, adapter dispatch, the commit token, and `ai-note`.
+
+```sh
+zsh tests/run.sh     # offline unit tests
+zsh tests/smoke.sh   # live: launches each agent headlessly, checks it responds
+```
+
+`smoke.sh` makes real API calls, so each CLI must be installed and authed
+(opencode defaults to DeepSeek; set it up or pass
+`AIMEM_SMOKE_OPENCODE_MODEL=provider/model`).
+
+## Design notes
+
+- **The vault is the source of truth; the chat is disposable.** Durable state lives
+  in Markdown, not in any agent's memory.
+- **Path-guarded writes.** Every file operation is checked to stay inside
+  `$AI_MEM_ROOT`, so an agent can't write outside the memory boundary.
+- **Project = git repo.** Resolution prefers the repo you're standing in, so
+  `cd`-ing between projects in one shell never pins the wrong project.
+- **Additive by default.** Templates fill in; notes are never clobbered.
+
+## Roadmap
+
+- Bash port of the shell module.
+- Publish `create-ai-memory` to npm.
+- More agent adapters shipped by default: opencode, aider.
+- Optional cross-project index and search over session logs.
+
+PRs welcome. Persistent AI memory shouldn't be a personal hack; it should be
+something the whole community can install.
+
+## License
+
+MIT © Ram Christopher Baarde

package/bin/create-ai-memory.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * create-ai-memory: set up ai-memory with no git clone.
+ *
+ * The tool's files are bundled inside this npm package, so this script just
+ * copies them into place and hands off to the shell installer, which owns the
+ * interactive setup (banner, prompts, vault scaffold, ~/.zshrc lines). No git,
+ * no network beyond the npm download itself.
+ *
+ * Usage:
+ *   npm create ai-memory@latest              # into ~/ai-memory
+ *   npx create-ai-memory ~/code/ai-memory    # into a directory you choose
+ */
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { cpSync, existsSync, mkdirSync } = require('node:fs');
+const { join, resolve } = require('node:path');
+const { homedir } = require('node:os');
+
+const pkgRoot = resolve(__dirname, '..');                       // bundled tool
+const dest = resolve(process.argv[2] || join(homedir(), 'ai-memory'));
+
+// Files that make up the tool; copied verbatim from the package into dest.
+const ITEMS = ['shell', 'hooks', 'vault-template', 'install.sh', 'create-ai-memory.plugin.zsh', 'LICENSE'];
+
+console.log(`create-ai-memory: installing into ${dest}`);
+mkdirSync(dest, { recursive: true });
+for (const item of ITEMS) {
+  const src = join(pkgRoot, item);
+  if (existsSync(src)) cpSync(src, join(dest, item), { recursive: true });
+}
+
+// Hand off to the shell installer for the interactive setup.
+const r = spawnSync('sh', [join(dest, 'install.sh')], { stdio: 'inherit' });
+if (r.error) {
+  console.error(`create-ai-memory: could not run install.sh: ${r.error.message}`);
+  console.error(`Files are in ${dest}; run  sh ${join(dest, 'install.sh')}  yourself.`);
+  process.exit(1);
+}
+process.exit(r.status ?? 0);

package/create-ai-memory.plugin.zsh

@@ -0,0 +1,5 @@
+# Entry point for zsh plugin managers (zinit, antidote, oh-my-zsh, antigen),
+# which load a repo by sourcing a root-level *.plugin.zsh. It just sources the
+# real module, resolved relative to this file so it works wherever the manager
+# clones the repo.
+source "${0:A:h}/shell/ai-mem.zsh"

package/hooks/claude/session-start.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Claude Code SessionStart hook for the AI-memory vault.
+#
+# Records the repo HEAD at session start so the matching summary hook can show
+# exactly which commits this session produced. No-ops unless the session was
+# launched via claude-start (which exports AI_MEM_ACTIVE_SESSION_LOG), so plain
+# `claude` runs are untouched.
+set -euo pipefail
+
+log="${AI_MEM_ACTIVE_SESSION_LOG:-}"
+[ -n "$log" ] || exit 0
+
+sha="$(git rev-parse HEAD 2>/dev/null || true)"
+[ -n "$sha" ] || exit 0
+
+printf '%s\n' "$sha" > "${log%.md}.startsha"

package/hooks/claude/session-summary.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Claude Code Stop hook for the AI-memory vault.
+#
+# Idempotently writes a concrete "Auto Session Log" block (branch, commits made
+# this session, and uncommitted changes) into the active session log, so the
+# NEXT session has real carryover instead of an empty template. Runs on every
+# Stop and rewrites a single block, so the log always reflects the latest state
+# even if the session is later killed abruptly.
+#
+# No-ops unless the session was launched via claude-start (which exports
+# AI_MEM_ACTIVE_SESSION_LOG).
+set -euo pipefail
+
+log="${AI_MEM_ACTIVE_SESSION_LOG:-}"
+[ -n "$log" ] || exit 0
+[ -f "$log" ] || exit 0
+
+marker="## Auto Session Log"
+
+branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '(no git)')"
+repo="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+
+start_sha=""
+[ -f "${log%.md}.startsha" ] && start_sha="$(cat "${log%.md}.startsha" 2>/dev/null || true)"
+
+commits=""
+if [ -n "$start_sha" ]; then
+    commits="$(git log --no-merges --format='- %h %s' "${start_sha}..HEAD" 2>/dev/null || true)"
+fi
+[ -n "$commits" ] || commits="- (no commits this session)"
+
+changes="$(git status --short 2>/dev/null | sed 's/^/- /' || true)"
+[ -n "$changes" ] || changes="- (working tree clean)"
+
+stamp="$(date '+%Y-%m-%d %H:%M:%S')"
+
+block="$(cat <<EOF
+${marker}
+_Auto-generated ${stamp}. Edit the Session Outcome section above for durable notes._
+
+* **Repo:** ${repo:-?}
+* **Branch:** ${branch}
+* **Commits this session:**
+${commits}
+* **Uncommitted changes at last checkpoint:**
+${changes}
+EOF
+)"
+
+# Strip any previous auto block (from marker to EOF), then append the fresh one.
+tmp="$(mktemp)"
+awk -v m="$marker" 'index($0, m)==1 { exit } { print }' "$log" > "$tmp"
+printf '%s\n\n%s\n' "$(cat "$tmp")" "$block" > "$log"
+rm -f "$tmp"

package/hooks/claude/settings.snippet.json

@@ -0,0 +1,19 @@
+{
+  "_comment": "Merge into ~/.claude/settings.json. Replace <AI_MEM_HOME> with the absolute path to your ai-mem checkout (Claude Code does not expand env vars in hook commands). Both hooks no-op unless the session was launched via claude-start.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "<AI_MEM_HOME>/hooks/claude/session-start.sh" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "<AI_MEM_HOME>/hooks/claude/session-summary.sh" }
+        ]
+      }
+    ]
+  }
+}

package/hooks/git/commit-msg

@@ -0,0 +1,178 @@
+#!/bin/sh
+# Enforce Conventional Commits with a detailed body and an active vault-context
+# token for this repository.
+# Git-generated merge, revert, fixup, and squash commits are allowed so common
+# history maintenance workflows still work without manual overrides.
+set -eu
+
+commit_msg_file=${1:-}
+
+if [ -z "$commit_msg_file" ] || [ ! -f "$commit_msg_file" ]; then
+  echo "commit-msg: expected a commit message file path" >&2
+  exit 1
+fi
+
+first_subject=''
+body_line_count=0
+body_word_count=0
+state=need_separator
+subject_skipped=0
+
+is_footer_line() {
+  case $1 in
+    BREAKING\ CHANGE:*|Signed-off-by:*|Co-authored-by:*|Reviewed-by:*|Acked-by:*|Refs\ *|Fixes\ *|Closes\ *|Resolves\ *)
+      return 0
+      ;;
+  esac
+
+  return 1
+}
+
+require_vault_context() {
+  local repo_root project_name ready_dir ready_file ready_token
+
+  if [ -z "${AI_MEM_ROOT:-}" ]; then
+    echo "commit-msg: AI_MEM_ROOT is not set; run ai-context first" >&2
+    return 1
+  fi
+
+  repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 1
+  project_name="$(basename "$repo_root")"
+  ready_dir="$AI_MEM_ROOT/_session_logs/.context-ready"
+  ready_file="$ready_dir/$project_name.token"
+
+  if [ ! -f "$ready_file" ]; then
+    echo "commit-msg: load the vault context first with ai-context" >&2
+    return 1
+  fi
+
+  if [ -z "${AI_MEM_CONTEXT_TOKEN:-}" ]; then
+    echo "commit-msg: this shell has not loaded the vault context; run ai-context first" >&2
+    return 1
+  fi
+
+  ready_token="$(sed -n '1p' "$ready_file")"
+
+  if [ "$ready_token" != "$AI_MEM_CONTEXT_TOKEN" ]; then
+    echo "commit-msg: this shell's vault context token does not match the active session; rerun ai-context" >&2
+    return 1
+  fi
+}
+
+while IFS= read -r line || [ -n "$line" ]; do
+  case $line in
+    '')
+      continue
+      ;;
+    '#'*)
+      continue
+      ;;
+  esac
+  first_subject=$line
+  break
+done < "$commit_msg_file"
+
+if [ -z "$first_subject" ]; then
+  echo "commit-msg: commit message is empty" >&2
+  exit 1
+fi
+
+case $first_subject in
+  Merge\ *|Revert\ *|fixup!\ *|squash!\ *)
+    exit 0
+    ;;
+esac
+
+if printf '%s\n' "$first_subject" | grep -Eq '^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\([^()[:space:]][^()[:space:]]*\))?(!)?: [^[:space:]].*$'; then
+  :
+else
+  cat >&2 <<'EOF'
+Commit message rejected.
+
+Use Conventional Commits:
+  type(scope): description
+
+Use a structured body after a blank line:
+  - short summary paragraph
+  - optional Why / Cause paragraph
+  - `-` bullet concrete changes or defenses
+  - optional notes or follow-up
+
+Examples:
+  feat(tmux): add session color sync
+  fix(zsh): avoid duplicate prompt initialization
+  docs(memory): clarify commit policy
+
+Allowed types:
+  feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
+
+Git-generated Merge, Revert, fixup!, and squash! messages are allowed.
+EOF
+
+  exit 1
+fi
+
+while IFS= read -r line || [ -n "$line" ]; do
+  case $line in
+    '#'*)
+      continue
+      ;;
+  esac
+
+  if [ "$subject_skipped" -eq 0 ]; then
+    case $line in
+      '')
+        continue
+        ;;
+    esac
+    subject_skipped=1
+    continue
+  fi
+
+  if [ "$state" = need_separator ]; then
+    if [ -z "$line" ]; then
+      state=body
+      continue
+    fi
+
+    echo "commit-msg: add a blank line after the subject, then a detailed body" >&2
+    exit 1
+  fi
+
+  if [ "$state" = footer ]; then
+    continue
+  fi
+
+  if [ -z "$line" ]; then
+    continue
+  fi
+
+  if is_footer_line "$line"; then
+    if [ "$body_line_count" -eq 0 ]; then
+      echo "commit-msg: add a detailed body before footers" >&2
+      exit 1
+    fi
+    state=footer
+    continue
+  fi
+
+  body_line_count=$((body_line_count + 1))
+  words=$(printf '%s\n' "$line" | awk '{print NF}')
+  body_word_count=$((body_word_count + words))
+done < "$commit_msg_file"
+
+if [ "$body_line_count" -eq 0 ]; then
+  echo "commit-msg: commit message needs a structured body, not just a title" >&2
+  exit 1
+fi
+
+if [ "$body_line_count" -lt 2 ] && [ "$body_word_count" -lt 20 ]; then
+  echo "commit-msg: body is too short; add a summary and - bullet changes or defenses" >&2
+  exit 1
+fi
+
+if ! require_vault_context; then
+  exit 1
+fi
+
+exit 0

package/hooks/git/pre-push

@@ -0,0 +1,19 @@
+#!/bin/sh
+# Block pushes that target the production branch unless an explicit override is
+# set for an emergency release.
+set -eu
+
+allow_main_push=${ALLOW_PUSH_TO_MAIN:-}
+
+while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
+  case $remote_ref in
+    refs/heads/main)
+      if [ "$allow_main_push" != "1" ]; then
+        echo "pre-push: push to main blocked; use a topic branch or set ALLOW_PUSH_TO_MAIN=1 for an explicit override" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
+exit 0