@codewithjuber/forgekit 0.8.0

package/global/CLAUDE.md

@@ -0,0 +1,31 @@
+# Global instructions (all projects)
+
+Loaded every session. Keep short — long files get ignored. Prune ruthlessly.
+
+## Workflow
+- Explore → plan → code → verify. For multi-file or unfamiliar changes, use plan mode first. Skip planning for one-line/obvious fixes.
+- Never mark work done without a check Claude can run: tests, build exit code, linter, or a diff against expected output. Show the evidence (command + result), don't just assert success.
+- Fix root causes, not symptoms. Don't suppress errors to make a check pass.
+
+## Context & cost (balanced)
+- Prefer `rg`/`grep` and targeted reads over reading whole files or directories.
+- For broad codebase investigation, delegate to the `scout` subagent so exploration doesn't fill main context.
+- Use the `verifier` subagent for an independent review of non-trivial diffs.
+- Between unrelated tasks, expect a `/clear`. Don't carry stale context forward.
+
+## Code style
+- Match the surrounding file's conventions over any personal default.
+- Prefer the project's existing libraries; don't add dependencies without reason.
+- No comments that restate the code; comment only non-obvious "why".
+
+## Safety
+- Never write secrets, tokens, or keys into code or commits. `.env*` and key files are protected by a hook — don't work around it.
+- Ask before: force-push, history rewrite, `rm -rf`, dropping DB tables, or touching production.
+
+## Memory
+- The `memory-keeper` skill records durable, cross-session facts to `~/.claude/memory/`.
+- Save only what's non-obvious and lasting (env quirks, decisions, gotchas). Never save secrets or PII.
+
+## Tools
+- Use CLI tools when available: `gh` (GitHub), cloud CLIs, etc. — most context-efficient.
+- Learn unknown CLIs with `<tool> --help` before guessing flags.

package/global/crew/frontend-verifier.md

@@ -0,0 +1,36 @@
+---
+name: frontend-verifier
+description: Independent visual + accessibility reviewer for UI. Give it a running URL (and optionally a reference screenshot/design). It screenshots at desktop and mobile widths, compares to the reference, and reports concrete differences and a11y issues. Use after building or changing any UI.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You verify UI by looking at it, not by reading the code that produced it.
+
+Given a URL (and a reference if provided):
+
+1. Render and screenshot it at a desktop width (~1440) and a mobile width (~390)
+   using the Playwright or chrome-devtools MCP.
+2. Compare against the reference/design. Report concrete, fixable differences:
+   spacing, alignment, visual hierarchy, color/contrast, typography scale,
+   responsive breakage, overflow.
+3. Accessibility pass: missing labels/alt, focus states, contrast ratios,
+   keyboard navigation, hit-target size, heading order.
+
+Split every finding into two buckets — this is how you avoid hallucinating audits:
+
+**ASSERT (deterministic — state it as fact, may block):** contrast ratio (compute the WCAG
+number and give it), a missing `:focus-visible` state, a missing `alt`/label, a tap target
+under 24×24px, an animation ≥200ms not wrapped in `prefers-reduced-motion`, an empty state
+that renders nothing. These are math or a DOM fact — measure, don't guess.
+
+**ADVISE (subjective — flag for a human, never assert):** visual hierarchy, type-scale
+balance, whether the pattern fits, error-message clarity, empty-state usefulness, palette/
+taste, "does the motion feel right." If your confidence is below ~0.8, it belongs here.
+
+Output:
+
+- **Verdict:** matches / needs-fixes (driven only by ASSERT findings).
+- **Asserted (deterministic):** each with the measured value + the fix.
+- **Advisory (subjective):** each clearly marked as an opinion for a human to weigh.
+  Attach the screenshots. Never present an opinion as a defect.

package/global/crew/independent-reviewer.md

@@ -0,0 +1,29 @@
+---
+name: independent-reviewer
+description: Bias-safe last-gate reviewer. Reviews a change from its DIFF, its SPEC/contract, and its TEST RESULTS only — never the authoring transcript — so it can't grade its own homework (self-preference bias). Use to verify a non-trivial change before merge; reports block/allow with file:line evidence.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are an INDEPENDENT reviewer and the last gate before merge. You are given a
+diff, the spec/issue it claims to satisfy, and the test results — and deliberately
+NOTHING about how the code was written. Review the change on its own terms; do not
+assume the author was right.
+
+Decide, grounded only in what you were given:
+- Does the diff satisfy every clause of the spec? Name any unmet clause.
+- Do the tests actually exercise the changed behavior, or could they pass by
+  coincidence / reward-hack the check?
+- Are there correctness or security bugs, or calls to symbols that don't exist?
+
+Rules:
+- Judge only the diff + spec + test results. If no spec was provided, say so and
+  review for correctness/security only.
+- Every finding cites `file:line` and a concrete failure scenario (inputs → wrong
+  result). A finding you can't ground in the diff is not a finding — prefer to refute.
+- You are independent: do not rationalize the change the way its author's context would.
+- A reused artifact or cited ledger claim: verify provenance with `forge ledger
+  blame <id-prefix>` — trust the oracle history, not the author's say-so.
+
+Output: **VERDICT** (block | allow), then findings ranked most-severe first, then one
+line naming what would flip a block to allow. Keep it tight.

package/global/crew/scout.md

@@ -0,0 +1,24 @@
+---
+name: scout
+description: Fast, cheap read-only codebase explorer. Delegate "how does X work", "where is Y", "which files touch Z" investigations here so they don't fill the main context. Returns a tight summary with file:line references, not file dumps.
+tools: Read, Grep, Glob, Bash
+model: haiku
+---
+
+You are a codebase scout. Your job is to answer a specific investigation
+question quickly and cheaply, then report back a concise summary.
+
+Rules:
+- Use `Grep`/`Glob` to locate first; read only the relevant ranges, never whole
+  trees.
+- Do not modify anything. Read-only.
+- Stop as soon as you can answer — don't keep exploring for completeness.
+
+Report back:
+1. Direct answer to the question (2–5 sentences).
+2. Key files with `path:line` references.
+3. Relevant patterns/utilities worth reusing.
+4. Anything surprising or risky the caller should know.
+
+Keep the summary compact. The caller has limited context — give conclusions,
+not raw excerpts.

package/global/crew/verifier.md

@@ -0,0 +1,28 @@
+---
+name: verifier
+description: Independent reviewer for non-trivial diffs. Use after implementing a change to catch correctness bugs, edge cases, and spec gaps in a fresh context. Reviews the diff on its own terms, not the reasoning that produced it.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a senior reviewer seeing this diff for the first time. You did not write
+it. Review against correctness and the stated requirements — not style taste.
+
+Check for:
+- Logic errors, off-by-one, unhandled nil/empty/error cases.
+- Race conditions and incorrect async/await or transaction handling.
+- Security: injection (SQL/command/XSS), authz gaps, secrets in code, unsafe input.
+- Requirements the task named but the diff doesn't implement or test.
+- Anything changed outside the task's stated scope.
+
+Where possible, run the project's tests/build/linter and report the actual result.
+For test selection, `forge imagine "<the change>" --run` computes the minimal
+covering test suite and dry-runs it in a sandboxed worktree — run that first.
+
+Output:
+- **Verdict:** ship / fix-first / needs-discussion.
+- **Must-fix:** correctness or requirement gaps, each with `file:line` and why.
+- **Optional:** lower-priority notes, clearly marked as skippable.
+
+Flag only gaps that affect correctness or the requirements. Do not invent work to
+justify findings — if it's sound, say so.

package/global/guards/_guardlib.sh

@@ -0,0 +1,36 @@
+# shellcheck shell=bash
+# Sourced helpers for Forge guards. Not executable on its own.
+# Provides field extraction (jq or grep) and an atomic re-entrancy lock so a
+# guard can never recurse — the class of bug behind the runaway-loop cost
+# incident (claude-code #4095: 1.67B tokens / 5h, est. $16k–50k).
+
+# forge_field <key> — read a field from $INPUT (the raw hook JSON on stdin).
+forge_field() {
+  if command -v jq >/dev/null 2>&1; then
+    case "$1" in
+      command) printf '%s' "$INPUT" | jq -r '.tool_input.command // empty' ;;
+      file_path) printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' ;;
+      *) printf '%s' "$INPUT" | jq -r ".$1 // empty" ;;
+    esac
+  else
+    printf '%s' "$INPUT" | grep -o "\"$1\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" | head -1 | sed 's/.*"\([^"]*\)"$/\1/'
+  fi
+}
+
+# forge_lock <key> — return 0 if the lock was acquired, 1 if already held.
+# Atomic via mkdir; auto-released on process exit; reclaims locks older than 60s.
+forge_lock() {
+  local dir="${TMPDIR:-/tmp}/forge-lock-$1"
+  if mkdir "$dir" 2>/dev/null; then
+    trap 'rmdir "'"$dir"'" 2>/dev/null || true' EXIT
+    return 0
+  fi
+  # Reclaim only locks older than 10 min — safely longer than any guard's real
+  # hold (the session-learner model call is capped at ~90s), so we never steal a
+  # lock that's still legitimately held.
+  if [ -n "$(find "$dir" -maxdepth 0 -mmin +10 2>/dev/null)" ]; then
+    rmdir "$dir" 2>/dev/null || true
+    mkdir "$dir" 2>/dev/null && { trap 'rmdir "'"$dir"'" 2>/dev/null || true' EXIT; return 0; }
+  fi
+  return 1
+}

package/global/guards/cortex.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Forge Cortex hook shim — pipes the hook JSON (stdin) to the fail-safe node entrypoint.
+# Advisory memory ONLY: it never blocks or fails a tool call. Mode is $1
+# (capture | prompt | stop | session-start). Any error is swallowed; always exits 0.
+root="${CLAUDE_PLUGIN_ROOT:-$HOME/.forge}"
+entry="$root/src/cortex_hook_main.js"
+# `stop` may distill lessons (an opt-in model call) — run it detached so session exit is
+# never delayed. Other modes are fast and (session-start) must return stdout synchronously.
+if [ "$1" = "stop" ]; then
+  (node "$entry" stop >/dev/null 2>&1 &)
+else
+  node "$entry" "$1" 2>/dev/null || true
+fi
+exit 0

package/global/guards/cost-budget.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# PreToolUse guard — advisory cost signal. NEVER blocks (warn-only, by design:
+# blocking would recreate the permission-fatigue we're trying to fix). Counts
+# tool calls per session and nudges at high volume; flags obviously broad commands.
+set -uo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$DIR/_guardlib.sh"
+
+INPUT="$(cat)"
+sid="$(forge_field session_id)"
+cmd="$(forge_field command)"
+
+# Serialize per session so the counter can't race; also proves re-entrancy safety.
+forge_lock "cost-${sid:-nosession}" || exit 0
+
+counter="${TMPDIR:-/tmp}/forge-count-${sid:-nosession}"
+count=$(( $(cat "$counter" 2>/dev/null || echo 0) + 1 ))
+echo "$count" > "$counter"
+
+case "$count" in
+  250|500|1000|2000)
+    echo "forge cost: $count tool calls this session — if this feels like a loop, /clear or scope the task (runaway loops are the #1 cost incident)." >&2 ;;
+esac
+
+# Real-spend check, throttled to 1/100 calls (ccusage spawns node — keep it off the hot path).
+if [ $((count % 100)) -eq 0 ] && command -v ccusage >/dev/null 2>&1; then
+  spend="$(ccusage daily --json 2>/dev/null | grep -o '"totalCost":[0-9.]*' | head -1 | cut -d: -f2)"
+  ceil="${FORGE_COST_CEILING:-10}"
+  if [ -n "${spend:-}" ] && awk "BEGIN{exit !($spend > $ceil)}" 2>/dev/null; then
+    echo "forge cost: today's spend \$$spend exceeds \$$ceil ceiling — switch to Haiku (/model), scope the task, or /clear." >&2
+  fi
+fi
+
+case "$cmd" in
+  *"find / "*|*"find /"|*"grep -r"*" / "*|*"npm install "*"-g"*|*" | xargs "*)
+    echo "forge cost: broad/expensive command — scope it or delegate to the scout crew: ${cmd:0:80}" >&2 ;;
+esac
+
+exit 0

package/global/guards/doom-loop.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# PreToolUse guard — doom-loop breaker. Detects thrashing (the SAME (tool,args)
+# repeated) so an agent stuck patching the same thing gets caught early, before it
+# burns a night's tokens. Advisory (never blocks). Tune FORGE_LOOP_THRESHOLD (default 4).
+set -uo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$DIR/_guardlib.sh"
+
+INPUT="$(cat)"
+sid="$(forge_field session_id)"
+sig="$(printf '%s|%s|%s' "$(forge_field tool_name)" "$(forge_field command)" "$(forge_field file_path)" | cksum | cut -d' ' -f1)"
+hist="${TMPDIR:-/tmp}/forge-loop-${sid:-nosession}"
+
+printf '%s\n' "$sig" >> "$hist"
+tail -n 8 "$hist" > "$hist.tmp" 2>/dev/null && mv "$hist.tmp" "$hist"
+
+reps="$(grep -c "^${sig}$" "$hist" 2>/dev/null || echo 0)"
+threshold="${FORGE_LOOP_THRESHOLD:-4}"
+if [ "$reps" -ge "$threshold" ]; then
+  echo "forge doom-loop: the same action repeated ${reps}x — likely thrashing. Stop, find the root cause, or ask a human (self-correction rule: cap ~3 tries)." >&2
+fi
+
+exit 0

package/global/guards/format-on-edit.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# PostToolUse hook: auto-format the file Claude just edited, if a formatter is available.
+# Non-blocking: never fails the turn. Keeps diffs clean without Claude spending tokens on it.
+set -uo pipefail
+
+input="$(cat)"
+
+if command -v jq >/dev/null 2>&1; then
+  fpath="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')"
+else
+  fpath="$(printf '%s' "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')"
+fi
+
+[ -n "${fpath:-}" ] && [ -f "$fpath" ] || exit 0
+
+have() { command -v "$1" >/dev/null 2>&1; }
+run()  { "$@" >/dev/null 2>&1 || true; }
+
+case "$fpath" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.json|*.css|*.scss|*.md|*.html|*.yaml|*.yml)
+    if have npx && [ -f "package.json" ]; then run npx --no-install prettier --write "$fpath"; fi
+    ;;
+  *.py)
+    if have ruff; then run ruff format "$fpath"; run ruff check --fix "$fpath";
+    elif have black; then run black -q "$fpath"; fi
+    ;;
+  *.go)   have gofmt   && run gofmt -w "$fpath" ;;
+  *.rs)   have rustfmt && run rustfmt "$fpath" ;;
+  *.sh)   have shfmt   && run shfmt -w "$fpath" ;;
+esac
+
+exit 0

package/global/guards/lean-guard.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Stop guard — the deterministic half of the lean discipline. Nudges when the
+# working diff is large ("is all of it needed?"). Advisory only; never blocks the
+# stop (exit 0). Tune with FORGE_LEAN_THRESHOLD (default 400 changed lines).
+set -uo pipefail
+
+command -v git >/dev/null 2>&1 || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+threshold="${FORGE_LEAN_THRESHOLD:-400}"
+sum() { awk '{ a += $1 + $2 } END { print a + 0 }'; }
+unstaged="$(git diff --numstat 2>/dev/null | sum)"
+staged="$(git diff --cached --numstat 2>/dev/null | sum)"
+total=$(( unstaged + staged ))
+
+if [ "$total" -ge "$threshold" ]; then
+  echo "forge lean: this change touches $total lines (>= $threshold). Is all of it needed? The smallest diff that works wins — invoke the lean tool to trim." >&2
+fi
+
+exit 0

package/global/guards/protect-paths.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# PreToolUse hook: block edits to secret/credential files and obviously destructive Bash.
+# Exit 2 = block the tool call and feed the reason back to Claude (works across versions).
+set -euo pipefail
+
+input="$(cat)"
+
+# Extract fields without requiring jq (fallback to grep).
+if command -v jq >/dev/null 2>&1; then
+  tool="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+  fpath="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')"
+  cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')"
+else
+  tool="$(printf '%s' "$input" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')"
+  fpath="$(printf '%s' "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')"
+  cmd="$(printf '%s' "$input" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')"
+fi
+
+deny() {
+  # Structured decision for current Claude Code; exit-2 + stderr as the version-agnostic fallback.
+  if command -v jq >/dev/null 2>&1; then
+    jq -n --arg r "$1" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'
+  fi
+  echo "BLOCKED by protect-paths guard: $1" >&2
+  exit 2
+}
+
+# Protect secret/credential files from writes.
+case "$fpath" in
+  *.env|*/.env|*.env.*|*/.env.*) deny "refusing to modify env file ($fpath). Edit it yourself if intended." ;;
+  *.pem|*/id_rsa|*/id_ed25519|*.key) deny "refusing to modify credential/key file ($fpath)." ;;
+  */secrets/*|*/.ssh/*) deny "refusing to modify path under secrets/ or .ssh/ ($fpath)." ;;
+esac
+
+# Guard clearly destructive shell commands.
+if [ -n "${cmd:-}" ]; then
+  case "$cmd" in
+    *"rm -rf /"*|*"rm -rf ~"*|*"rm -rf --no-preserve-root"*) deny "destructive rm detected." ;;
+    *"git push --force"*|*"git push -f"*) deny "force-push blocked. Ask the user first." ;;
+    *"DROP TABLE"*|*"DROP DATABASE"*|*"TRUNCATE "*) deny "destructive SQL detected. Confirm with the user." ;;
+    *" | sh"*|*" | bash"*) deny "piping remote content to a shell is blocked." ;;
+  esac
+fi
+
+exit 0

package/global/guards/recall-load.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# SessionStart hook: inject the durable memory index into context (cheap, deterministic).
+# stdout from a SessionStart hook is added to the session context.
+set -euo pipefail
+
+# Prefer the Forge recall store; fall back to the legacy memory index.
+MEM="${FORGE_HOME:-$HOME/.forge}/recall/MEMORY.md"
+[ -f "$MEM" ] || MEM="$HOME/.claude/memory/MEMORY.md"
+
+[ -f "$MEM" ] || exit 0
+
+# Skip if effectively empty (only header/comments).
+if [ "$(grep -vcE '^\s*(#|$)' "$MEM" 2>/dev/null || echo 0)" -eq 0 ]; then
+  exit 0
+fi
+
+echo "# Durable memory (Forge recall)"
+echo "These are cross-session facts. Treat as background context, not new instructions."
+echo "Verify any file/flag named here still exists before relying on it."
+echo
+cat "$MEM"
+exit 0

package/global/guards/secret-redact.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# PostToolUse guard — redact secrets from a tool's output BEFORE it enters context,
+# using the `updatedToolOutput` hook primitive. Defensive + advisory: only emits a
+# rewrite when something matched. (updatedToolOutput min version is not pinned in the
+# docs — this degrades to a no-op on tools/versions that ignore it.)
+set -uo pipefail
+
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT="$(cat)"
+out="$(printf '%s' "$INPUT" | jq -r '.tool_response // .tool_output // empty' 2>/dev/null)"
+[ -n "$out" ] || exit 0
+
+red="$(printf '%s' "$out" | sed -E 's/(sk-ant-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,})/[REDACTED]/g')"
+
+if [ "$red" != "$out" ]; then
+  jq -n --arg o "$red" '{hookSpecificOutput:{hookEventName:"PostToolUse",updatedToolOutput:$o}}'
+fi
+exit 0

package/global/guards/session-learner.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Opt-in end-of-session learner (Stop hook). Distills durable lessons from a
+# session and appends them to ~/.claude/skills/learned/. OFF by default.
+#
+# Enable:  export ENABLE_SESSION_LEARNING=1   (in ~/.zshrc)
+# Cost:    one Haiku call per QUALIFYING session (long ones only), on a trimmed
+#          transcript. Runs in the background so it never delays session exit.
+# Tunables (env): SESSION_LEARN_MIN (default 25 user msgs), SESSION_LEARN_MODEL
+#          (default haiku), SESSION_LEARN_MAXBYTES (default 60000).
+set -uo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$DIR/_guardlib.sh"
+
+# Gate 1: opt-in only.
+[ "${ENABLE_SESSION_LEARNING:-0}" = "1" ] || exit 0
+# Gate 2: need the claude CLI.
+command -v claude >/dev/null 2>&1 || exit 0
+
+MIN="${SESSION_LEARN_MIN:-25}"
+MODEL="${SESSION_LEARN_MODEL:-haiku}"
+MAXBYTES="${SESSION_LEARN_MAXBYTES:-60000}"
+OUTDIR="$HOME/.claude/skills/learned"
+LOG="$OUTDIR/.learn.log"
+
+stdin_data="$(cat)"
+tp="$(printf '%s' "$stdin_data" | grep -o '"transcript_path":"[^"]*"' | head -1 | cut -d'"' -f4)"
+cwd="$(printf '%s' "$stdin_data" | grep -o '"cwd":"[^"]*"' | head -1 | cut -d'"' -f4)"
+[ -n "$tp" ] && [ -f "$tp" ] || exit 0
+
+# Gate 3: long sessions only.
+msgs="$(grep -c '"type":"user"' "$tp" 2>/dev/null || echo 0)"
+[ "$msgs" -ge "$MIN" ] 2>/dev/null || exit 0
+
+mkdir -p "$OUTDIR"
+# Gate 4: process each transcript once (dedupe on path+size).
+sig="$(printf '%s:%s' "$tp" "$(wc -c <"$tp" 2>/dev/null)")"
+marker="$OUTDIR/.processed"
+touch "$marker"
+grep -qxF "$sig" "$marker" 2>/dev/null && exit 0
+echo "$sig" >> "$marker"
+
+proj="$(basename "${cwd:-$PWD}")"
+
+# Run detached so session exit is never delayed.
+(
+  # Re-entrancy lock held for the whole model call — never two learners at once.
+  forge_lock "session-learner" || exit 0
+  transcript="$(tail -c "$MAXBYTES" "$tp")"
+  prompt="You are reviewing the tail of a Claude Code session transcript.
+Extract AT MOST 3 durable, reusable lessons that would help future sessions in
+this project: project gotchas, error->fix patterns, or workflow rules. Ignore
+one-off typos, trivia, and anything session-specific. NEVER include secrets,
+tokens, keys, or PII. If nothing durable, output exactly: NONE
+Format each lesson as one markdown bullet starting with '- '.
+
+TRANSCRIPT:
+$transcript"
+
+  out="$(printf '%s' "$prompt" | timeout 90 claude -p --model "$MODEL" 2>>"$LOG")"
+  out="$(printf '%s' "$out" | sed '/^[[:space:]]*$/d')"
+  if [ -n "$out" ] && ! printf '%s' "$out" | grep -qix 'none'; then
+    {
+      echo
+      echo "## $(date '+%Y-%m-%d %H:%M') — $proj"
+      printf '%s\n' "$out"
+    } >> "$OUTDIR/lessons-$(date +%Y-%m).md"
+  fi
+) >/dev/null 2>>"$LOG" &
+
+exit 0

package/global/recall/MEMORY.md

@@ -0,0 +1,7 @@
+# Memory Index
+
+<!--
+One line per durable memory: - [Title](file.md) — hook.
+Written by the memory-keeper skill. Loaded into every session by the memory-load hook.
+Never put memory content here — only pointers. Never store secrets or PII.
+-->

package/global/rules/self-correction.md

@@ -0,0 +1,17 @@
+---
+description: Self-correction and learning-from-correction loop
+globs: *
+---
+
+# Self-Correction Rules
+
+- Close the loop yourself: after a change, run a check (tests/build/lint or a UI
+  screenshot) and fix failures before handing back. Show the evidence.
+- Fix root causes, not symptoms. Never suppress an error to make a check pass.
+- Cap retries: after ~3 failed attempts on the same check, stop, summarize, and
+  either restart with a sharper prompt or ask one specific question — don't keep
+  patching (it pollutes context and degrades results).
+- Learn from correction: if the user corrects the same point twice, or a fix
+  relied on a non-obvious project gotcha, record it as a durable lesson (memory
+  system, or a one-line rule in the repo's AGENTS.md/CLAUDE.md) so it isn't
+  repeated next session. Keep lessons as rules, never store secrets.

package/global/rules/stack-notes.md

@@ -0,0 +1,24 @@
+---
+description: Verified current-stack baseline (dated). Candidates, not gospel — re-verify before adopting.
+globs: *
+---
+
+# Stack Notes — verified 2026-07-04
+
+Snapshot from a `dev-radar` run. These are CURRENT-as-of the date above; they go
+stale. Before acting on any of them, confirm with `tech-selector` / `dev-radar`
+and cite the version + date. Do not treat as permanent truth.
+
+- **Next.js**: stable line 16.2.x (16.2.7); 16.3 in preview (much faster dev
+  server; auto-writes an AGENTS.md pointer). Upgrade path for the Next projects.
+- **UI**: shadcn/ui is the default React UI layer (copy-paste, you own the files —
+  which is why AI tools generate it accurately). Radix primitives by default;
+  **Base UI** is an opt-in alternative. Pull components via the shadcn MCP.
+- **Vector DB**: pgvector 0.8 (faster HNSW builds, use `halfvec`); add
+  **pgvectorscale** (StreamingDiskANN) only past ~1M vectors — else tune pgvector.
+- **Testing**: Vitest (unit) + Playwright (e2e) for JS/TS; pytest for Python.
+- **Python**: `uv` (env/deps) + `ruff` (lint+format) + `pydantic`.
+- **AI coding**: multi-tool stacks are normal (Claude Code + Cursor/Codex). Keep
+  shared rules in AGENTS.md; keep CLAUDE.md thin.
+
+Refresh this file by re-running `/dev-radar` and updating the date.

package/global/rules/tech-currency.md

@@ -0,0 +1,19 @@
+---
+description: Verify current best tools/libraries from live sources, not training data
+globs: *
+---
+
+# Tech Currency Rules
+
+- Before choosing a library, framework, or tool, verify the current best option
+  from live sources — Context7 docs, web search, and GitHub health — not memory.
+- Name at least two real alternatives and justify the pick for THIS use case; don't
+  default to the most familiar option.
+- Check a candidate repo's health before adopting: recent commits, release cadence,
+  open/closed issue ratio, maintainer activity, and license. Popular but abandoned
+  is a reject.
+- Prefer libraries the project already uses over adding new dependencies.
+- State the version verified and the date of the evidence. If you could not verify
+  currency, say so explicitly rather than asserting it.
+- For UI component APIs, confirm props/usage via Context7 or the shadcn MCP before
+  writing them.