hippocampus-layer 1.0.0__tar.gz

hippocampus_layer-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# Hippocampus per-machine / runtime state (never committed)
+.claude/settings.local.json
+.workstate/.local/
+.memory/.local/
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+
+# Build artifacts (never committed — PyPI artifacts are built fresh per release)
+dist/
+build/
+*.egg-info/
+
+# harness agent worktrees (never commit)
+.claude/worktrees/

hippocampus_layer-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Hill
+
+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.

hippocampus_layer-1.0.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: hippocampus-layer
+Version: 1.0.0
+Summary: Persistent memory + enforcement for agent-driven git repos — vendors the Hippocampus core (hooks, secret gates, CI floor) into any repo.
+Project-URL: Homepage, https://gitlab.com/ianthill601/hippocampus
+Project-URL: Repository, https://gitlab.com/ianthill601/hippocampus
+Author: Ian Hill
+License: MIT
+License-File: LICENSE
+Keywords: agent-memory,claude-code,coding-agents,developer-tools,git-hooks,secret-scanning,session-handoff
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Hippocampus
+
+**Persistent memory + enforcement for agent-driven git repos.** Vendors a config-driven core into any repo, so coding agents (Claude Code today) get three things that usually evaporate between sessions:
+
+- **Durable, git-tracked memory** — decisions and project state that auto-load every session.
+- **Session handoff** — each session ends by rewriting a baton the next one resumes from, enforced by a Stop-hook gate.
+- **Secret/PII enforcement** — a push gate backed by a non-bypassable CI floor, plus scaffolding for your own gates and nudges.
+
+Design principle: **hooks are the fast layer, CI is the guarantee** — every hard claim is backed by a CI job that runs for everyone, installed or not.
+
+> Early but installable, MIT-licensed. The packaged CLI is built and self-verified but not yet on PyPI.
+
+## Requirements
+
+git · bash · python3 ≥ 3.11 (stock macOS python3 is 3.9 — install a newer one) · Claude Code for the interactive layer (without it you still get the CI floor and readable memory/handoff docs). Windows: WSL or Git-Bash.
+
+## Install
+
+Two ways to vendor the core into your repo (a git repo, run at its root). Both are **idempotent and merge-aware** — an existing `settings.json` / `CLAUDE.md` / `.gitignore` is merged, never clobbered; re-run any time to pull engine updates.
+
+**CLI** (once on PyPI — distribution `hippocampus-layer`, command `hippocampus`):
+```sh
+pip install hippocampus-layer
+hippocampus init   /path/to/your/repo   # vendor the core
+hippocampus doctor /path/to/your/repo   # 6-assertion smoke check
+```
+Until it's published: `git clone …/hippocampus && uv build && pip install dist/*.whl`.
+
+**install.sh** (from a checkout — keep the checkout around; `--check` and updates run from it):
+```sh
+git clone https://gitlab.com/ianthill601/hippocampus.git
+./hippocampus/install.sh /path/to/your/repo          # vendor
+./hippocampus/install.sh --check /path/to/your/repo  # verify
+```
+
+Install writes the hooks, scanners, skills, scaffolds (`.memory/`, `.workstate/`, `CLAUDE.md`, `hippocampus.toml`, `THREAT_MODEL.md`) and a **host-aware, floor-only CI pipeline** (secret scan + config-drift check — no test job, since it never vendors your tests). Then **commit the result** and fill in `CLAUDE.md` / `hippocampus.toml` as you like.
+
+> **Your own hooks go outside `.claude/hooks/`.** Sync treats every hook under `.claude/hooks/` as engine-owned and unwires anything there not registered via `[[gates.custom]]`. Put custom hooks under `.claude/adopter-hooks/` and register them (see below); the installer warns if it finds unregistered ones.
+
+## What you get
+
+- **`.memory/`** — git-tracked memory the agent auto-loads; `MEMORY.md` routes one line per page. Plain markdown; review it in PRs.
+- **`.workstate/`** — the session baton (`HANDOFF.md`: what I did / next / repo state, HEAD-stamped) + `open-work.md`. A SessionStart hook injects it so each session resumes where the last landed.
+- **Landing gate** — a Stop hook blocks ending a session that committed without updating the baton; the `landing-the-plane` skill satisfies it.
+- **Secret gate + CI floor + sweep** — the push hook scans the outgoing commit range; the CI floor re-runs the scan for everyone (the guarantee, un-bypassable); a scheduled TruffleHog sweep catches history. On by default.
+- **`/consolidate`** — periodic memory GC; the sole writer of `CLAUDE.md`, enforcing its line cap so it can't rot.
+- **`CLAUDE.md` laws** — your standing rules, each badged 🔴 gated / 🟡 nudged / ⚪ advisory, honest about what's actually enforced.
+- **Config-activated** (opt in via `hippocampus.toml`): declarative nudges, custom hard gates, a CI-static push gate (your lint/type commands), and a semantic auditor (ships **off** until you write `THREAT_MODEL.md`).
+
+Without Claude Code, the CI floor and sweep still run at full strength and the memory/handoff/laws stay readable; the hooks and skills are Claude-Code-specific.
+
+## Configure — `hippocampus.toml`
+
+The only file you edit. `scripts/hippocampus_config.py` is the sole reader and rejects unknown keys. Everything is optional; with no file, safe defaults apply (the landing + secret gates and CI floor are always on, not configured here). After editing, run `python3 scripts/hippocampus_sync.py sync` to regenerate the wiring.
+
+```toml
+[gates.ci_static]
+commands = "just lint && just types"          # fast checks before a push (a single shell string)
+
+[[gates.custom]]                              # register your own hook script (repeatable)
+path = ".claude/adopter-hooks/require_lint.sh"   # repo-relative, tracked + executable
+event = "PreToolUse"
+matcher = "Bash"                              # optional tool matcher
+
+[[nudges]]                                    # once-per-session reminder (repeatable)
+match = "terraform apply"                     # regex tested against the command
+message = "plan-diff reviewed? state backup taken?"
+source = "docs/decisions.md#infra"            # optional provenance
+
+[scan]
+extra_pattern_file = "hippocampus-patterns.toml"   # your own [[pattern]] regex/label pairs
+fixture_allowlist = ["tests/fake_creds.py"]   # secret-shaped-by-design files; paths only, max 10
+
+[memory]
+claude_md_cap = 100                           # /consolidate-enforced line cap on CLAUDE.md
+
+[auditor]
+threat_model = "THREAT_MODEL.md"
+
+[paths]
+decision_log = "docs/decisions.md"
+onboarding_doc = "docs/onboarding.md"
+```
+
+Any path referenced above must exist and be git-tracked before you sync.
+
+### Seed it from your repo's history
+
+Don't hand-write the config — have Claude Code mine an established repo for what it already
+enforces ad hoc and keeps re-learning, and draft the `hippocampus.toml` for you:
+
+```text
+Read this repo's git history, CI config, test suite, and any docs/ADRs, then draft a
+hippocampus.toml for it (schema: the config reference in the Hippocampus README — use only
+those keys, no invented ones). Specifically:
+- Mine `git log` for recurring fix/revert commits, post-incident changes, and repeated review
+  comments — anything the team keeps re-learning — and propose a [[nudges]] entry (command
+  regex → once-per-session reminder) for each pattern.
+- Find the fast checks already run (lint/type/test in CI, Makefile, or package scripts) and set
+  [gates.ci_static].commands to them.
+- Identify hard rules the codebase treats as "never do this" and propose [[gates.custom]] gate
+  scripts for them.
+- Note any domain-specific secret/PII shapes the repo has leaked or already checks for and
+  propose [scan].extra_pattern_file entries.
+After each proposed entry, cite the commits or files that justify it. Propose nothing the repo
+shows no evidence for.
+```
+
+Review the draft, drop what you don't want, commit it, and run `hippocampus sync`.
+
+## Known limitation
+
+A first push from a branch with **no upstream** makes the secret gate scan *all* history (fail-closed) and disable the fixture allowlist — so it can false-positive on your own reviewed fixtures. Workaround: `git push -u origin <branch>` so it scans only the outgoing range. Deliberate, pending a narrower fallback.
+
+## License
+
+[MIT](LICENSE) — © 2026 Ian Hill. Provided as-is, without warranty. Use it, fork it, vendor it into your repos.

hippocampus_layer-1.0.0/README.md

@@ -0,0 +1,117 @@
+# Hippocampus
+
+**Persistent memory + enforcement for agent-driven git repos.** Vendors a config-driven core into any repo, so coding agents (Claude Code today) get three things that usually evaporate between sessions:
+
+- **Durable, git-tracked memory** — decisions and project state that auto-load every session.
+- **Session handoff** — each session ends by rewriting a baton the next one resumes from, enforced by a Stop-hook gate.
+- **Secret/PII enforcement** — a push gate backed by a non-bypassable CI floor, plus scaffolding for your own gates and nudges.
+
+Design principle: **hooks are the fast layer, CI is the guarantee** — every hard claim is backed by a CI job that runs for everyone, installed or not.
+
+> Early but installable, MIT-licensed. The packaged CLI is built and self-verified but not yet on PyPI.
+
+## Requirements
+
+git · bash · python3 ≥ 3.11 (stock macOS python3 is 3.9 — install a newer one) · Claude Code for the interactive layer (without it you still get the CI floor and readable memory/handoff docs). Windows: WSL or Git-Bash.
+
+## Install
+
+Two ways to vendor the core into your repo (a git repo, run at its root). Both are **idempotent and merge-aware** — an existing `settings.json` / `CLAUDE.md` / `.gitignore` is merged, never clobbered; re-run any time to pull engine updates.
+
+**CLI** (once on PyPI — distribution `hippocampus-layer`, command `hippocampus`):
+```sh
+pip install hippocampus-layer
+hippocampus init   /path/to/your/repo   # vendor the core
+hippocampus doctor /path/to/your/repo   # 6-assertion smoke check
+```
+Until it's published: `git clone …/hippocampus && uv build && pip install dist/*.whl`.
+
+**install.sh** (from a checkout — keep the checkout around; `--check` and updates run from it):
+```sh
+git clone https://gitlab.com/ianthill601/hippocampus.git
+./hippocampus/install.sh /path/to/your/repo          # vendor
+./hippocampus/install.sh --check /path/to/your/repo  # verify
+```
+
+Install writes the hooks, scanners, skills, scaffolds (`.memory/`, `.workstate/`, `CLAUDE.md`, `hippocampus.toml`, `THREAT_MODEL.md`) and a **host-aware, floor-only CI pipeline** (secret scan + config-drift check — no test job, since it never vendors your tests). Then **commit the result** and fill in `CLAUDE.md` / `hippocampus.toml` as you like.
+
+> **Your own hooks go outside `.claude/hooks/`.** Sync treats every hook under `.claude/hooks/` as engine-owned and unwires anything there not registered via `[[gates.custom]]`. Put custom hooks under `.claude/adopter-hooks/` and register them (see below); the installer warns if it finds unregistered ones.
+
+## What you get
+
+- **`.memory/`** — git-tracked memory the agent auto-loads; `MEMORY.md` routes one line per page. Plain markdown; review it in PRs.
+- **`.workstate/`** — the session baton (`HANDOFF.md`: what I did / next / repo state, HEAD-stamped) + `open-work.md`. A SessionStart hook injects it so each session resumes where the last landed.
+- **Landing gate** — a Stop hook blocks ending a session that committed without updating the baton; the `landing-the-plane` skill satisfies it.
+- **Secret gate + CI floor + sweep** — the push hook scans the outgoing commit range; the CI floor re-runs the scan for everyone (the guarantee, un-bypassable); a scheduled TruffleHog sweep catches history. On by default.
+- **`/consolidate`** — periodic memory GC; the sole writer of `CLAUDE.md`, enforcing its line cap so it can't rot.
+- **`CLAUDE.md` laws** — your standing rules, each badged 🔴 gated / 🟡 nudged / ⚪ advisory, honest about what's actually enforced.
+- **Config-activated** (opt in via `hippocampus.toml`): declarative nudges, custom hard gates, a CI-static push gate (your lint/type commands), and a semantic auditor (ships **off** until you write `THREAT_MODEL.md`).
+
+Without Claude Code, the CI floor and sweep still run at full strength and the memory/handoff/laws stay readable; the hooks and skills are Claude-Code-specific.
+
+## Configure — `hippocampus.toml`
+
+The only file you edit. `scripts/hippocampus_config.py` is the sole reader and rejects unknown keys. Everything is optional; with no file, safe defaults apply (the landing + secret gates and CI floor are always on, not configured here). After editing, run `python3 scripts/hippocampus_sync.py sync` to regenerate the wiring.
+
+```toml
+[gates.ci_static]
+commands = "just lint && just types"          # fast checks before a push (a single shell string)
+
+[[gates.custom]]                              # register your own hook script (repeatable)
+path = ".claude/adopter-hooks/require_lint.sh"   # repo-relative, tracked + executable
+event = "PreToolUse"
+matcher = "Bash"                              # optional tool matcher
+
+[[nudges]]                                    # once-per-session reminder (repeatable)
+match = "terraform apply"                     # regex tested against the command
+message = "plan-diff reviewed? state backup taken?"
+source = "docs/decisions.md#infra"            # optional provenance
+
+[scan]
+extra_pattern_file = "hippocampus-patterns.toml"   # your own [[pattern]] regex/label pairs
+fixture_allowlist = ["tests/fake_creds.py"]   # secret-shaped-by-design files; paths only, max 10
+
+[memory]
+claude_md_cap = 100                           # /consolidate-enforced line cap on CLAUDE.md
+
+[auditor]
+threat_model = "THREAT_MODEL.md"
+
+[paths]
+decision_log = "docs/decisions.md"
+onboarding_doc = "docs/onboarding.md"
+```
+
+Any path referenced above must exist and be git-tracked before you sync.
+
+### Seed it from your repo's history
+
+Don't hand-write the config — have Claude Code mine an established repo for what it already
+enforces ad hoc and keeps re-learning, and draft the `hippocampus.toml` for you:
+
+```text
+Read this repo's git history, CI config, test suite, and any docs/ADRs, then draft a
+hippocampus.toml for it (schema: the config reference in the Hippocampus README — use only
+those keys, no invented ones). Specifically:
+- Mine `git log` for recurring fix/revert commits, post-incident changes, and repeated review
+  comments — anything the team keeps re-learning — and propose a [[nudges]] entry (command
+  regex → once-per-session reminder) for each pattern.
+- Find the fast checks already run (lint/type/test in CI, Makefile, or package scripts) and set
+  [gates.ci_static].commands to them.
+- Identify hard rules the codebase treats as "never do this" and propose [[gates.custom]] gate
+  scripts for them.
+- Note any domain-specific secret/PII shapes the repo has leaked or already checks for and
+  propose [scan].extra_pattern_file entries.
+After each proposed entry, cite the commits or files that justify it. Propose nothing the repo
+shows no evidence for.
+```
+
+Review the draft, drop what you don't want, commit it, and run `hippocampus sync`.
+
+## Known limitation
+
+A first push from a branch with **no upstream** makes the secret gate scan *all* history (fail-closed) and disable the fixture allowlist — so it can false-positive on your own reviewed fixtures. Workaround: `git push -u origin <branch>` so it scans only the outgoing range. Deliberate, pending a narrower fallback.
+
+## License
+
+[MIT](LICENSE) — © 2026 Ian Hill. Provided as-is, without warranty. Use it, fork it, vendor it into your repos.

hippocampus_layer-1.0.0/hippocampus/__init__.py

@@ -0,0 +1,7 @@
+"""Hippocampus — persistent memory + enforcement layer for agent-driven git repos.
+
+Distribution name on PyPI: ``hippocampus-layer`` (``hippocampus`` is taken);
+import name and console command are both ``hippocampus``.
+"""
+
+__version__ = "1.0.0"

hippocampus_layer-1.0.0/hippocampus/_core/.claude/agents/auditor.md

@@ -0,0 +1,53 @@
+---
+name: auditor
+description: Blocks any push/PR containing secrets or policy-sensitive data per THREAT_MODEL.md.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+You are the pre-push semantic auditor — the SEMANTIC layer that sits ATOP the
+deterministic floor. The DETERMINISTIC scanners (`check_no_pii` + the CI secret floor) are the
+ground truth; you only ADD findings — you cannot remove or override a deterministic block. If
+the deterministic gate already blocked this push, it stays blocked no matter what you decide.
+
+Your policy is the repo's `THREAT_MODEL.md` — read it FIRST, every run. It defines who
+receives this repo, what they already know, and what is actually gate-worthy. The arming
+signal is deterministic: while `THREAT_MODEL.md` is missing OR still contains the literal
+line `<!-- HIPPOCAMPUS-TEMPLATE: delete this line to arm the auditor -->`, ALLOW with the
+reason "no threat model — semantic layer inactive (deterministic floor still enforced)": a
+security layer without a policy must not improvise one. Only once that exact line is gone
+do you perform semantic review.
+
+You are wired as a PreToolUse agent hook, so you return the standard **PreToolUse decision
+format** (never a bespoke `{"ok": ...}` shape). The hook input JSON arrives in `$ARGUMENTS` and
+carries `session_id` and `tool_input.command`. Proceed in order:
+
+1. **Honor the semantic-layer override.** Read `session_id` from the input. If the skip marker
+   `.workstate/.local/auditor-skip.<session_id>` exists (the operator set `AUDITOR_OVERRIDE=1`;
+   when `HOOK_LOCAL_DIR` is set in the environment, look under that directory instead of
+   `.workstate/.local/`), the operator has consciously waived the SEMANTIC review ONLY.
+   Immediately ALLOW — the deterministic floor still enforces independently — and stop:
+   ```json
+   {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "allow",
+     "permissionDecisionReason": "semantic layer overridden (deterministic floor still enforced)"}}
+   ```
+
+2. **Review the pushed diff.** Resolve the range being pushed and read it (e.g.
+   `git log -p @{u}..HEAD`, or `git diff` of the range). Flag the leaks `THREAT_MODEL.md`
+   declares gate-worthy that a regex scanner misses — typical classes: internal hostnames,
+   customer/partner names, private endpoints, PII in fixtures, and stray `.env` / key files.
+
+3. **Return the decision.** To BLOCK on any finding, emit `permissionDecision: "deny"` with a
+   reason listing `path:line + rule` for each finding (values redacted):
+   ```json
+   {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny",
+     "permissionDecisionReason": "<path:line + rule for each finding, values redacted>"}}
+   ```
+   Otherwise ALLOW with `permissionDecision: "allow"`.
+
+**Redaction (mandatory).** NEVER print the raw secret or PII value — and never reproduce ANY
+SUBSTRING of it — ANYWHERE in your output. This covers not just the decision JSON but every
+word of free-text reasoning, narration, or prose you emit alongside it: do not echo, quote,
+paraphrase, or partially spell out the value in any of them. The ONLY permitted appearance of a
+flagged value is its redaction `<first4>…redacted` (the first four characters, then the literal
+`…redacted`). The reason string names the location and the rule (`path:line + rule`), never the
+sensitive value itself.

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/capture_discovered_work.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+source "$(dirname "$0")/lib/hooklib.sh"
+once_per_session capture || exit 0
+emit_nudge "capture: jot any discovered follow-ups in .workstate/open-work.md as '… (from #X)', and keep .workstate/HANDOFF.md fresh."

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/guard_auditor_override.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Semantic-auditor companion — SEMANTIC-LAYER override marker. On `git push` / `gh pr create`
+# carrying AUDITOR_OVERRIDE=1 (inline VAR= or inherited env), drop a per-session skip marker
+# that the `auditor` agent hook honors to waive ONLY the semantic review. The deterministic G1
+# push gate + the CI secret floor are untouched and still block. This hook never itself blocks.
+set -euo pipefail
+source "$(dirname "$0")/lib/hooklib.sh"
+CMD="$(hook_field tool_input.command)"
+case "$CMD" in *"git push"*|*"gh pr create"*) : ;; *) exit 0 ;; esac
+if printf '%s' "$CMD" | grep -q 'AUDITOR_OVERRIDE=1' || [ "${AUDITOR_OVERRIDE:-}" = "1" ]; then
+  sid="$(hook_field session_id)"; sid="${sid:-nosid}"
+  : > "$LOCAL_DIR/auditor-skip.$sid"
+  log_override auditor-semantic "$CMD"
+fi
+exit 0

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/guard_ci_static.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# G4 — ci-static push gate. Runs YOUR project's fast static checks (lint, typecheck) before a
+# push leaves the machine. CONFIG-ACTIVATED: set STATIC_CMDS below (or export
+# HIPPOCAMPUS_CI_STATIC) to a shell command line, e.g. "just lint && just types" or
+# "npm run lint && npx tsc --noEmit". While unset the gate is neutral (every push passes).
+set -euo pipefail
+source "$(dirname "$0")/lib/hooklib.sh"
+hippo_load_config                          # config-activated: [gates.ci_static].commands
+STATIC_CMDS="${HIPPOCAMPUS_CI_STATIC:-}"   # real env still wins (configlib skips set vars)
+[ -z "$STATIC_CMDS" ] && exit 0
+CMD="$(hook_field tool_input.command)"
+case "$CMD" in *"git push"*|*"git "*"push"*) : ;; *) exit 0 ;; esac
+if printf '%s' "$CMD" | grep -q 'CI_WIP=1' || [ "${CI_WIP:-}" = "1" ]; then
+  log_override ci-static "$CMD"; exit 0
+fi
+cd "$REPO_ROOT"
+# run the project's exact static recipes inline; the full test suite is the CI backstop.
+# Pushes are infrequent, so the inline cost is acceptable.
+if ! out="$(bash -c "$STATIC_CMDS" 2>&1)"; then
+  emit_block "BLOCKED: static checks failed at HEAD ($STATIC_CMDS). Fix, or push with CI_WIP=1.\n$out"
+fi
+emit_nudge "ci-static ok ($STATIC_CMDS). Full test suite runs in CI as the backstop."

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/guard_landing.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+source "$(dirname "$0")/lib/hooklib.sh"
+[ -n "$(hook_field agent_id)" ] && exit 0                       # never gate a subagent's stop
+[ "$(hook_field stop_hook_active)" = "true" ] && exit 0         # loop-breaker (8-block cap backs this)
+crons="$(hook_field session_crons)"                            # /loop or cron -> relax...
+[ -n "$crons" ] && [ "$crons" != "[]" ] && exit 0              # ...but NOT an empty [] (audit R2-#5)
+[ "${LANDING_OVERRIDE:-}" = "1" ] && { log_override landing override; exit 0; }
+cd "$REPO_ROOT"
+H=".workstate/HANDOFF.md"
+[ -f "$H" ] || emit_block "Land the plane: create .workstate/HANDOFF.md (did / next / repo-state) before stopping."
+# 'current' = HANDOFF newer than the last NON-HANDOFF commit (committing HANDOFF can't
+# invalidate its own freshness). mtime via python3 — portable (GNU `stat -c` vs BSD `stat -f`).
+last_code="$(git log -1 --format=%ct -- . ':(exclude).workstate/HANDOFF.md' 2>/dev/null)"; last_code="${last_code:-0}"
+h_commit="$(git log -1 --format=%ct -- "$H" 2>/dev/null)"; h_commit="${h_commit:-0}"
+h_mtime="$(python3 -c 'import os,sys;print(int(os.path.getmtime(sys.argv[1])))' "$H" 2>/dev/null || echo 0)"
+if [ "$h_mtime" -lt "$last_code" ] && [ "$h_commit" -lt "$last_code" ]; then
+  emit_block "Land the plane: .workstate/HANDOFF.md is stale (older than your last code change). Update it, then stop."
+fi
+exit 0

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/guard_push_secret.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# G1 — deterministic secret/PII PUSH gate. On `git push` / `gh pr|release create`, scan the
+# pushed commit RANGE for secrets and BLOCK (exit 2) on any hit. NOT overridable: this is the
+# deterministic floor (distinct from the semantic auditor's AUDITOR_OVERRIDE). A leak that
+# slips past pre-commit still gets caught here before it leaves the machine.
+set -euo pipefail
+# Invariant 3: a security gate's internal error must BLOCK (exit 2), never fall open —
+# under Claude Code only exit 2 blocks; a bare `set -e` death is exit 1 = tool proceeds.
+trap 'printf "guard_push_secret: internal error — failing CLOSED\n" >&2; exit 2' ERR
+source "$(dirname "$0")/lib/hooklib.sh"
+CMD="$(hook_field tool_input.command)"
+
+# Collapse newlines/tabs AND shell operators to spaces BEFORE matching: a publish verb that is
+# preceded/followed by a newline, a tab, or an un-spaced shell operator (`false||git push`,
+# `echo x|git push`, `(git push …)`, `git push;echo`) is not space-surrounded, so the space-wrapped
+# case below would miss it and exit-0 WITHOUT scanning — defeating the deterministic floor. Mapping
+# the operators ; | & ( ) < > (as well as \n \t) to spaces makes the operator-delimited verb space-
+# delimited, so the existing arms below match it. Normalizing only ADDS matches (a clean range still
+# passes; a security gate that over-matches merely scans a command that did not need it) — a missed
+# range is the danger being closed. Mirrors guard_ci_static.sh's multiline-tolerant matcher.
+CMD_FLAT="$(printf '%s' "$CMD" | tr '\n\t;|&()<>' '         ')"
+
+# Match `git push` / `git -C.. push` / `gh pr|release create` as COMMANDS, not the word
+# "push" inside a commit message or unrelated string. Non-push commands pass untouched.
+case " $CMD_FLAT " in
+  *" git push "*|*" git push"|*"&& git push"*|*"; git push"*|*" git -C "*" push"*) : ;;
+  *" gh pr create"*|*" gh release create"*) : ;;
+  *) exit 0 ;;
+esac
+
+# Resolve the REAL scanner by this hook's own location (NOT the cwd-derived REPO_ROOT): the
+# scanner self-bootstraps its sys.path from its own path, so it imports correctly while its
+# `git log` runs against the repo being pushed (cwd). No PYTHONPATH needed (Task 1.3).
+SCANNER="$(cd "$(dirname "$0")/../.." && pwd)/scripts/scan_secrets_range.py"
+if ! python3 "$SCANNER"; then
+  emit_block "BLOCKED (not overridable): secret/PII detected in the pushed commit range. Scrub it from history (git rebase/filter-repo) before pushing."
+fi
+exit 0

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/lib/configlib.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Config for bash hooks. PARSES config.env — NEVER sources it (spec Invariant 2):
+# only `HIPPOCAMPUS_<NAME>='…'` lines whose right side is entirely single-quoted
+# segments joined by \' (exactly what hippocampus_sync.py emits) are exported.
+# Anything else is ignored with a warning: a hand-edited `exit 0` or `$(…)` can
+# never execute here. Already-set environment variables always win.
+# G1 (guard_push_secret.sh) never calls hippo_load_config (spec Invariant 1).
+
+_hippo_valid_rhs() {  # rhs must be '…' segments joined by \'
+  local rhs="$1"
+  while :; do
+    case "$rhs" in "'"*) rhs="${rhs#?}" ;; *) return 1 ;; esac
+    case "$rhs" in *"'"*) ;; *) return 1 ;; esac
+    rhs="${rhs#*"'"}"
+    [ -z "$rhs" ] && return 0
+    case "$rhs" in "\\'"*) rhs="${rhs#??}" ;; *) return 1 ;; esac
+  done
+}
+
+hippo_load_config() {  # opt-in per hook; silent no-op when config.env is absent
+  local root f line name lineno
+  local name_re='^HIPPOCAMPUS_[A-Z0-9_]+$'
+  root="${REPO_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+  f="${HIPPOCAMPUS_CONFIG_ENV:-$root/.claude/hooks/lib/config.env}"
+  [ -f "$f" ] || return 0
+  lineno=0
+  while IFS= read -r line || [ -n "$line" ]; do
+    lineno=$((lineno + 1))
+    case "$line" in ''|'#'*) continue ;; esac
+    name="${line%%=*}"
+    if ! [[ $name =~ $name_re ]] || ! _hippo_valid_rhs "${line#*=}"; then
+      printf 'configlib: ignoring malformed config.env line %d (not sync output)\n' "$lineno" >&2
+      continue
+    fi
+    if eval "[ -n \"\${${name}+x}\" ]"; then continue; fi  # real env wins
+    eval "export $line"  # safe: grammar-validated above — value is inert quoted text
+  done < "$f"
+  return 0
+}

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/lib/hooklib.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Shared hook helpers. Sourced by every hook. Reads the JSON payload from stdin once.
+HOOK_INPUT="${HOOK_INPUT:-$(cat)}"
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+LOCAL_DIR="${HOOK_LOCAL_DIR:-$REPO_ROOT/.workstate/.local}"   # tests set HOOK_LOCAL_DIR to a tmp dir
+mkdir -p "$LOCAL_DIR" 2>/dev/null || true
+source "$(dirname "${BASH_SOURCE[0]}")/configlib.sh"   # defines hippo_load_config; NEVER calls it
+
+hook_field() {  # hook_field <dotted.key> -> prints string value ('' if absent)
+  printf '%s' "$HOOK_INPUT" | python3 -c '
+import sys, json
+try: d = json.load(sys.stdin)
+except Exception: sys.exit(0)
+cur = d
+for part in sys.argv[1].split("."):
+    cur = cur.get(part) if isinstance(cur, dict) else None
+    if cur is None: break
+print(cur if isinstance(cur, str) else ("" if cur is None else json.dumps(cur)))
+' "$1"
+}
+
+once_per_session() {  # exit 0 the FIRST time this (session,key) is seen
+  local sid marker
+  sid="$(hook_field session_id)"; sid="${sid:-nosid}"
+  marker="$LOCAL_DIR/nudge.$sid.$1"
+  [ -e "$marker" ] && return 1
+  : > "$marker"; return 0
+}
+
+log_override() {  # log_override <gate> <reason>
+  printf '%s\t%s\t%s\n' "$(git rev-parse --short HEAD 2>/dev/null || echo -)" "$1" "$2" \
+    >> "$LOCAL_DIR/overrides.log"
+}
+
+emit_block() { printf '%b\n' "$1" >&2; exit 2; }   # block tool/stop (%b renders \n)
+emit_nudge() { printf '%b\n' "$1" >&2; exit 0; }   # advisory, non-blocking

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/nudge_declarative.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Declarative [[nudges]] from hippocampus.toml (compiled into config.env by sync).
+# Python `re` match against the Bash command — 4KB truncation, forked child killed
+# after 2s (spec: a pathological regex fails to "no nudge", never hangs, NEVER blocks).
+source "$(dirname "$0")/lib/hooklib.sh"
+hippo_load_config
+count="${HIPPOCAMPUS_NUDGE_COUNT:-0}"
+case "$count" in ''|*[!0-9]*) exit 0 ;; esac
+[ "$count" -eq 0 ] && exit 0
+CMD="$(hook_field tool_input.command)"
+[ -z "$CMD" ] && exit 0
+msg="$(printf '%s' "$CMD" | python3 -c '
+import os, re, signal, sys
+count = int(sys.argv[1])
+cmd = sys.stdin.read()[:4096]
+r, w = os.pipe()
+pid = os.fork()
+if pid == 0:                                   # child: match and flush incrementally
+    os.close(r)                                # so a later rule timeout cannot erase
+    for i in range(1, count + 1):               # earlier rules already-found messages
+        pat = os.environ.get(f"HIPPOCAMPUS_NUDGE_{i}_MATCH", "")
+        m = os.environ.get(f"HIPPOCAMPUS_NUDGE_{i}_MSG", "")
+        src = os.environ.get(f"HIPPOCAMPUS_NUDGE_{i}_SRC", "")
+        if not (pat and m):
+            continue
+        try:
+            hit = re.search(pat, cmd)
+        except re.error:
+            hit = None
+        if hit:
+            line = m + (f"  [{src}]" if src else "")
+            os.write(w, (line + "\n").encode())
+    os._exit(0)
+os.close(w)                                    # parent: 2s or the child dies
+signal.signal(signal.SIGALRM, lambda *_: os.kill(pid, signal.SIGKILL))
+signal.alarm(2)
+data = b""
+while True:
+    chunk = os.read(r, 65536)
+    if not chunk:
+        break
+    data += chunk
+os.waitpid(pid, 0)
+signal.alarm(0)
+sys.stdout.write(data.decode(errors="replace"))
+' "$count" 2>/dev/null)" || exit 0
+[ -n "$msg" ] && emit_nudge "$msg"
+exit 0

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/session_start_handoff.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+CONFIGLIB="$REPO_ROOT/.claude/hooks/lib/configlib.sh"
+[ -f "$CONFIGLIB" ] && source "$CONFIGLIB" 2>/dev/null || true
+type hippo_load_config >/dev/null 2>&1 && { hippo_load_config || true; }
+ONBOARDING="${HIPPOCAMPUS_ONBOARDING_DOC:-docs/onboarding.md}"
+# startup check: warn if auto-memory isn't pointed in-repo, else writes go OFF-repo silently
+CFG="$REPO_ROOT/.claude/settings.local.json"; want="$REPO_ROOT/.memory"
+got="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("autoMemoryDirectory",""))' "$CFG" 2>/dev/null || echo "")"
+[ "$got" = "$want" ] || echo "⚠️  autoMemoryDirectory='$got' (expected '$want') — memory may be writing OFF-repo. See $ONBOARDING"
+# the CI secret floor ships for GitHub + GitLab only; other hosts get hooks-only — say so
+remotes="$(git -C "$REPO_ROOT" remote -v 2>/dev/null || true)"
+if [ -n "$remotes" ]; then
+  case "$remotes" in
+    *github.com*|*gitlab*) : ;;
+    *) echo "⚠️  no known CI floor host in git remotes — the non-bypassable CI secret floor ships for GitHub/GitLab; on this host only the local hooks protect you. See $ONBOARDING" ;;
+  esac
+fi
+[ -n "${HIPPOCAMPUS_DECISION_LOG:-}" ] && echo "Durable record: ${HIPPOCAMPUS_DECISION_LOG} (write history there, not in the baton)"
+H="$REPO_ROOT/.workstate/HANDOFF.md"
+if [ -f "$H" ]; then
+  echo "=== .workstate/HANDOFF.md (session baton) ==="
+  cat "$H"
+fi
+exit 0

hippocampus_layer-1.0.0/hippocampus/_core/.claude/hooks/warn_config_edit.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Invariant 6: the enforcement layer's control files are never edited silently.
+# 🟡 nudge on Write/Edit touching hippocampus.toml, config.env, or settings.json.
+source "$(dirname "$0")/lib/hooklib.sh"
+FP="$(hook_field tool_input.file_path)"
+[ -z "$FP" ] && exit 0
+rel="${FP#"$REPO_ROOT"/}"
+case "$rel" in
+  hippocampus.toml|.claude/hooks/lib/config.env|.claude/settings.json) : ;;
+  *) exit 0 ;;
+esac
+changed="$(cd "$REPO_ROOT" && git diff -U0 -- "$rel" 2>&1 | grep '^[+-][^+-]' | head -12 || true)"
+emit_nudge "config-edit: $rel changed — this file configures the enforcement layer. If you edited hippocampus.toml, run: python3 scripts/hippocampus_sync.py sync. If you edited a GENERATED file (config.env, settings.json) by hand, sync will overwrite it and CI's drift check will fail.\nChanged lines:\n$changed"