hippocampus-layer 1.0.0__py3-none-any.whl

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/_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/_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/_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/_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/_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/_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/_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/_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/_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/_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/_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"

hippocampus/_core/.claude/hooks/warn_silent_failure.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+source "$(dirname "$0")/lib/hooklib.sh"
+CMD="$(hook_field tool_input.command)"
+printf '%s' "$CMD" | grep -q '2>/dev/null' || exit 0
+printf '%s' "$CMD" | grep -Eq 'grep|test |\[ |if ' || exit 0
+emit_nudge "silent-command-failure: suppressed stderr + state inference — check the raw exit code FIRST; empty output != a state."

hippocampus/_core/.claude/skills/landing-the-plane/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: landing-the-plane
+description: "End-of-session handoff runbook — run this when you are wrapping up a working session, before you stop after making commits. Rewrites the `.workstate/HANDOFF.md` baton (what-I-did / what's-next / repo-state + a HEAD stamp) and reconciles `.workstate/open-work.md` so the next session resumes cleanly. Satisfies the G3 Stop gate (`.claude/hooks/guard_landing.sh`), which blocks a stop when the baton is stale."
+---
+
+# Landing the plane — end-of-session handoff
+
+Walk this **before you stop** at the end of a working session in which you committed
+anything. It hands the baton to the next session and clears the G3 Stop gate. The baton
+is `.workstate/HANDOFF.md`; the flat work list is `.workstate/open-work.md`. Both are
+tracked (only `.workstate/.local/` is git-ignored).
+
+## The workflow
+
+1. **Rewrite the three baton sections** in `.workstate/HANDOFF.md` — overwrite in place,
+   never duplicate-append:
+   - **What I did** — what changed this session (tasks, commits, decisions).
+   - **What's next** — the immediate next action, so a fresh controller can resume.
+   - **Repo state** — branch, HEAD, test status, and where the authoritative resume map lives.
+
+2. **Stamp the HEAD** as the last line: `<!-- HEAD: $(git rev-parse HEAD) -->`. This records
+   the commit the baton describes, so the gate can tell current from stale.
+
+3. **Reconcile `.workstate/open-work.md`** — close finished items (delete their lines), add
+   the follow-ups you discovered. Keep it a flat, one-item-per-line list.
+
+4. **Now it is safe to stop.** Land the plane *last*, after your final code commit: editing
+   the baton refreshes its mtime, so G3 passes.
+
+## What the gate checks (`.claude/hooks/guard_landing.sh`)
+
+- **Stop-only.** It fires when the main agent tries to stop; it never gates a subagent.
+- **Freshness by mtime.** It blocks only when the baton is **missing**, or **stale** — its
+  file mtime *and* its last commit are both older than the last non-`HANDOFF.md` commit. A
+  HANDOFF-only commit cannot refresh itself (the "last code change" excludes it), so a bare
+  edit — which bumps the mtime — is what clears the gate.
+- **Autonomous-aware.** It relaxes for a `/loop` or scheduled-cron session (a non-empty
+  `session_crons` list, not an empty `[]`) and for a re-entrant stop; `LANDING_OVERRIDE=1`
+  is the manual escape hatch.
+
+> The baton is ephemeral — a one-session pointer, not a log. The durable record is your
+> project's decision log and `.memory/` pages; write history there, not here.

hippocampus/_core/.claude/skills/memory-consolidation/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: memory-consolidation
+description: "Periodic manual memory garbage-collection runbook — invoke as /consolidate to tidy the `.memory/` store and the `.workstate/open-work.md` work list. Drives the deterministic ops in `scripts/consolidate_ops.py`: auto-applies the safe, git-tracked rewrites (dedupe, frontmatter repair, closed-work compaction, index reconcile) and flags the judgment calls (orphans + linker suggestions, negative-value pages, contradictions, coverage gaps) for a human to resolve. The sole writer of `CLAUDE.md`, under its ~100-line cap."
+model: opus
+---
+
+# Memory consolidation — the /consolidate manual GC
+
+Run this **when invoked as `/consolidate`** — a periodic, human-in-the-loop tidy of durable
+memory. It orchestrates the nine pure functions in `scripts/consolidate_ops.py` (import them;
+they only read the dir you hand them or transform strings you pass — **none delete, none write
+to disk**). Every write is yours, git-tracked and recoverable. Nothing here runs automatically:
+the ops classify, you decide, and the auto-apply class is the *only* class that mutates.
+
+The memory-store ops act on `.memory/` (topic pages + the `MEMORY.md` router index — the
+harness-owned store). The one exception is closed-work compaction, which acts on **our**
+`.workstate/open-work.md` flat list, not a `.memory/` page. Name the right target per op.
+
+## 1. Auto-apply — deterministic, safe, git-tracked
+
+Apply these directly; each is reversible via git.
+
+- **Dedupe.** `find_exact_duplicates(dir)` returns variadic tuples — the **N-way** groups of
+  byte-identical `*.md` pages. Collapse each group to one canonical page and re-point inbound
+  links to it. No information is lost (the members are byte-identical), so this is not a hard
+  delete of content — it removes redundant copies only.
+- **Frontmatter repair.** `repair_frontmatter(text)` guarantees an `updated:` key; the body is
+  preserved verbatim. Self-edit the page in place — **never** duplicate-append.
+- **Closed-work compaction.** `compact_closed_work(text)` on `.workstate/open-work.md` drops
+  completed `- [x]` and struck `~~…~~` lines while keeping open items and `(from #X)` lineage.
+- **Index reconcile.** `reconcile_index(dir)` returns `{"missing": [...], "dangling": [...]}`,
+  counting **only real markdown links** (a prose parenthetical is not a link). Add the missing
+  pages to `MEMORY.md`; remove the dangling links. Idempotent — a second run is a no-op.
+
+## 2. Flag-only — surface for a human, never auto-apply, never delete
+
+These are judgment calls. Report them in the run summary with a recommendation; **never delete**
+a page and never edit on your own initiative.
+
+- **Orphans + linker suggestions** (audit R2-#19). `find_orphans(dir)` lists pages with zero
+  inbound links. For each, suggest **where to link it from** — name the candidate sibling pages
+  whose content relates — so a human can wire it in. The linker suggestion is advice, not an edit.
+- **Negative-value pages.** `compression_flag(text)` is the operator-variant **compression
+  test**: `True` when a page draws on `<2` distinct sources — a single-source mirror of one
+  greppable file, which earns no keep. Flag it as negative-value; do not delete it.
+- **Contradiction / staleness / coverage-gap.** Where two pages disagree, a page has gone stale,
+  or a live topic has no page, flag it and defer to a human. When ambiguous, defer — do not guess.
+
+## 3. Guardrails (binding)
+
+- **Never delete.** No op deletes; you never hard-delete a page carrying unique content. The only
+  removal is collapsing byte-identical duplicates (§1).
+- **`CLAUDE.md` is written by /consolidate alone**, under its ~100-line cap. A promotion must
+  **displace**: `promote_with_displacement(claude_md, new_law, displaced_line)` appends the new
+  law only after removing `displaced_line` by **exact-line match**. Name a real, present line
+  verbatim — a wrong or absent line **fails loud** (`ValueError`). It post-verifies the cap and
+  refuses (`ValueError`) any result over 100 non-blank lines (`claude_md_lines`). At the cap with
+  no displacement it refuses. This task never actually writes `CLAUDE.md`; the skill only owns it.
+- **New-page vs edit-in-place.** A *new page* is a distinct entity you would `[[link]]`; an
+  *edit* is an attribute of one that exists. **Prefer editing.** A page is authoritative or it
+  should not exist — no per-read hedge.
+- **Idempotent.** Re-running /consolidate on a tidy store changes nothing.
+- **Emit `run_summary(actions)`** at the end — the human-readable log of what was applied and
+  what was flagged. It is never empty (`"consolidate run: no-op"` when nothing changed).
+
+> Where this file and `CLAUDE.md` differ, `CLAUDE.md` is canonical. The compression test,
+> new-page rule, and cap live there under "Memory conventions"; this skill enforces them.

hippocampus/_core/.github/workflows/secret-history-sweep.yml

@@ -0,0 +1,15 @@
+name: secret-history-sweep
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch: {}
+jobs:
+  trufflehog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: trufflesecurity/trufflehog@27b0417c16317ca9a472a9a8092acce143b49c55 # v3.95.9
+        with:
+          extra_args: --only-verified

hippocampus/_core/THREAT_MODEL.md

@@ -0,0 +1,43 @@
+# THREAT_MODEL.md — the semantic auditor's policy
+<!-- HIPPOCAMPUS-TEMPLATE: delete this line to arm the auditor -->
+
+The semantic auditor (`.claude/agents/auditor.md`) reviews every outbound push against THIS
+file. While the HIPPOCAMPUS-TEMPLATE sentinel line above exists, the auditor stays inactive —
+deleting that line (after writing real answers below) is the explicit, greppable arming
+step; a reformat or annotation of the template can never arm it by accident. The deterministic
+secret gate and the CI floor protect the repo regardless of what's written here.
+
+Answer the three questions that decide everything:
+
+## 1. Who receives this repo?
+
+<!-- e.g. "public — anyone on the internet", "a contractor under NDA", "internal team only".
+     TEMPLATE — replace me. -->
+
+## 2. What do they already know?
+
+<!-- Sensitivity is relative: a partner who already knows your org's name doesn't need the
+     name gated; a public release does. List what the recipient legitimately already knows,
+     so the auditor doesn't false-positive on it. TEMPLATE — replace me. -->
+
+## 3. What is actually gate-worthy?
+
+<!-- The classes of content that must NEVER leave in a push. Be concrete: e.g. customer
+     names, internal hostnames, unreleased product names, personal data of class X. The
+     deterministic scanners already handle credential shapes — list what only a READER
+     would catch. TEMPLATE — replace me. -->
+
+---
+
+**To activate the auditor** once this file is real, add the agent hook to
+`.claude/settings.json` under the `PreToolUse` → `"matcher": "Bash"` hook list:
+
+```json
+{ "type": "agent", "if": "Bash(git push *)", "model": "opus", "timeout": 120,
+  "prompt": "Run the `auditor` agent (.claude/agents/auditor.md) over the pushed diff for $ARGUMENTS. Block on any finding per THREAT_MODEL.md; redact values." }
+```
+
+Note the honest cost: the agent hook runs an LLM review on every push (latency + spend), and
+agent hooks fail open — the deterministic floor, not this layer, is the guarantee.
+`AUDITOR_OVERRIDE=1 git push …` waives one push's semantic review only (logged); nothing
+waives the deterministic floor.

hippocampus/_core/ci/gitlab-secret-history-sweep.yml

@@ -0,0 +1,16 @@
+# Scheduled deep-history TruffleHog sweep — GitLab parity with
+# .github/workflows/secret-history-sweep.yml. Runs ONLY on scheduled pipelines
+# (never on push/MR); create the schedule once at Build → Pipeline schedules
+# (weekly, e.g. cron "0 6 * * 1", matching the GitHub sweep).
+secret-history-sweep:
+  stage: check
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "schedule"'
+  image:
+    name: trufflesecurity/trufflehog:latest
+    entrypoint: [""]
+  variables:
+    GIT_STRATEGY: clone
+    GIT_DEPTH: "0"          # full clone — the sweep's whole point is deep history
+  script:
+    - trufflehog git file://. --only-verified --fail