threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/nudges.py

@@ -0,0 +1,257 @@
+"""Counter-driven nudge logic. Inspired by hermes-agent's
+memory_nudge_interval / skill_nudge_interval — when N mutating events
+have passed in this session since the last 'save event' (memory or skill),
+surface an active nudge in brief() asking the agent to consolidate.
+
+Unlike spawn_hint and skill_hint (passive observation of state), these
+nudges are turn-counter-driven: every mutating tool emits an event, the
+counter walks forward, and when it crosses a threshold the surface
+escalates from soft → hard → demanding.
+
+Public:
+    compute_memory_nudge(conn, session_id) -> Optional[str]
+        Returns the nudge text to embed in brief(), or None if quiet.
+    compute_skill_nudge(conn, session_id) -> Optional[str]
+        Same for skill consolidation.
+    auto_review_should_fire(conn, session_id) -> Optional[str]
+        Returns a thread_id IF auto-review should spawn now (rich closed
+        thread + threshold crossed + AUTO_REVIEW_ENABLED), else None.
+"""
+from __future__ import annotations
+
+import sqlite3
+import time
+from typing import Optional
+
+from .config import (
+    MEMORY_NUDGE_INTERVAL,
+    SKILL_NUDGE_INTERVAL,
+    AUTO_REVIEW_ENABLED,
+)
+
+
+# Event kinds that count as "memory save" — emitting any of these resets
+# the memory-nudge counter.
+_MEMORY_RESET_KINDS = (
+    "open_thread",
+    "close_thread",
+    "note:insight",
+    "note:move",
+    "core_set",
+    "verbatim_user",
+    "concept_register",
+    "distill",
+    "memory_save",
+)
+
+# Event kinds that count as "skill save" — emitting any of these resets
+# the skill-nudge counter.
+_SKILL_RESET_KINDS = (
+    "skill_create",
+    "skill_edit",
+    "skill_patch",
+    "skill_write_file",
+    "skill_materialized",
+)
+
+
+def _last_reset_event_id(conn: sqlite3.Connection, session_id: str,
+                         kinds: tuple[str, ...]) -> int:
+    """Return MAX(events.id) for this session matching any reset-kind, or 0."""
+    if not session_id or not kinds:
+        return 0
+    placeholders = ",".join("?" * len(kinds))
+    row = conn.execute(
+        f"SELECT COALESCE(MAX(id), 0) m FROM events "
+        f"WHERE session_id = ? AND kind IN ({placeholders})",
+        (session_id, *kinds),
+    ).fetchone()
+    if row is None:
+        return 0
+    return row["m"] if hasattr(row, "keys") else row[0]
+
+
+def _count_events_since(conn: sqlite3.Connection, session_id: str,
+                        since_id: int,
+                        exclude_kinds: tuple[str, ...]) -> int:
+    """Count events for session with id > since_id whose kind is NOT in
+    exclude_kinds. These are the "non-save" turns between the last save
+    and now."""
+    if not session_id:
+        return 0
+    if exclude_kinds:
+        placeholders = ",".join("?" * len(exclude_kinds))
+        row = conn.execute(
+            f"SELECT COUNT(*) c FROM events "
+            f"WHERE session_id = ? AND id > ? "
+            f"AND kind NOT IN ({placeholders})",
+            (session_id, since_id, *exclude_kinds),
+        ).fetchone()
+    else:
+        row = conn.execute(
+            "SELECT COUNT(*) c FROM events "
+            "WHERE session_id = ? AND id > ?",
+            (session_id, since_id),
+        ).fetchone()
+    if row is None:
+        return 0
+    return row["c"] if hasattr(row, "keys") else row[0]
+
+
+def _has_rich_thread(conn: sqlite3.Connection,
+                     min_notes: int = 3) -> bool:
+    """True if there's at least one active-or-closed thread with ≥ min_notes
+    notes total. Used by memory-nudge — there's something worth saving."""
+    try:
+        row = conn.execute(
+            "SELECT t.id "
+            "FROM threads t "
+            "WHERE t.state IN ('active','closed') "
+            "  AND (SELECT COUNT(*) FROM notes n WHERE n.thread_id=t.id) >= ? "
+            "LIMIT 1",
+            (min_notes,),
+        ).fetchone()
+    except sqlite3.OperationalError:
+        return False
+    return row is not None
+
+
+def _find_rich_pending_thread(conn: sqlite3.Connection,
+                              within_seconds: int = 86400) -> Optional[str]:
+    """Find the richest closed thread that hasn't been materialized into a
+    skill yet. Returns thread_id, or None.
+
+    Rich = ≥5 notes, ≥2 of kind 'insight' or 'move'. Recency: closed within
+    `within_seconds`. Suppressed when a 'skill_materialized' event already
+    exists for the thread.
+    """
+    now = int(time.time())
+    try:
+        row = conn.execute(
+            "SELECT t.id, "
+            "  (SELECT COUNT(*) FROM notes n WHERE n.thread_id=t.id) AS n_total, "
+            "  (SELECT COUNT(*) FROM notes n WHERE n.thread_id=t.id "
+            "   AND n.kind IN ('insight','move')) AS n_rich "
+            "FROM threads t "
+            "WHERE t.state='closed' AND t.last_touched_at > ? "
+            "  AND NOT EXISTS ("
+            "    SELECT 1 FROM events e "
+            "    WHERE e.kind='skill_materialized' AND e.target=t.id"
+            "  ) "
+            "  AND (SELECT COUNT(*) FROM notes n WHERE n.thread_id=t.id) >= 5 "
+            "  AND (SELECT COUNT(*) FROM notes n WHERE n.thread_id=t.id "
+            "       AND n.kind IN ('insight','move')) >= 2 "
+            "ORDER BY t.last_touched_at DESC LIMIT 1",
+            (now - within_seconds,),
+        ).fetchone()
+    except sqlite3.OperationalError:
+        return None
+    if row is None:
+        return None
+    return row["id"] if hasattr(row, "keys") else row[0]
+
+
+def compute_memory_nudge(conn: sqlite3.Connection,
+                         session_id: str) -> Optional[str]:
+    """Counter-driven memory consolidation nudge. Fires when this session's
+    event counter has crossed MEMORY_NUDGE_INTERVAL since the last memory
+    save AND there's a rich thread worth saving.
+
+    Returns the multi-line nudge text (to be embedded in brief()), or None.
+    """
+    if MEMORY_NUDGE_INTERVAL <= 0:
+        return None
+    if not session_id:
+        return None
+    last_id = _last_reset_event_id(conn, session_id, _MEMORY_RESET_KINDS)
+    n_since = _count_events_since(conn, session_id, last_id,
+                                  _MEMORY_RESET_KINDS)
+    if n_since < MEMORY_NUDGE_INTERVAL:
+        return None
+    if not _has_rich_thread(conn, min_notes=3):
+        return None
+    if n_since >= 2 * MEMORY_NUDGE_INTERVAL:
+        # demanding
+        return (
+            f"memory_nudge n_since={n_since} ⚠️ overdue=2x\n"
+            f"  → ⚠️ {n_since} events without a memory save "
+            f"(threshold was {MEMORY_NUDGE_INTERVAL}). MUST consolidate "
+            f"next: pick richest thread, write insight-note OR "
+            f"core_set()/verbatim_user() on the durable signal. "
+            f"Continuing without save = losing the work."
+        )
+    # soft
+    return (
+        f"memory_nudge n_since={n_since} target=memory "
+        f"threshold={MEMORY_NUDGE_INTERVAL}\n"
+        f"  → {n_since} events since last memory save. CONSOLIDATE: pick "
+        f"the most active thread, write a note(kind='insight') with what "
+        f"crystallized, or core_set() the durable lesson. Don't let "
+        f"context evaporate."
+    )
+
+
+def compute_skill_nudge(conn: sqlite3.Connection,
+                        session_id: str) -> Optional[str]:
+    """Counter-driven skill consolidation nudge. Fires when this session's
+    event counter has crossed SKILL_NUDGE_INTERVAL since the last skill
+    save AND there's a rich closed thread without a prior skill_materialized
+    event.
+    """
+    if SKILL_NUDGE_INTERVAL <= 0:
+        return None
+    if not session_id:
+        return None
+    last_id = _last_reset_event_id(conn, session_id, _SKILL_RESET_KINDS)
+    n_since = _count_events_since(conn, session_id, last_id,
+                                  _SKILL_RESET_KINDS)
+    if n_since < SKILL_NUDGE_INTERVAL:
+        return None
+    if _find_rich_pending_thread(conn) is None:
+        return None
+    if n_since >= 2 * SKILL_NUDGE_INTERVAL:
+        return (
+            f"skill_nudge n_since={n_since} ⚠️ overdue=2x\n"
+            f"  → ⚠️ {n_since} events without skill update "
+            f"(threshold was {SKILL_NUDGE_INTERVAL}). MUST act next: "
+            f"materialize the richest closed thread via "
+            f"review_thread(..., mode='auto') OR patch the most-relevant "
+            f"existing skill via skill_manage(action='patch')."
+        )
+    return (
+        f"skill_nudge n_since={n_since} target=skill "
+        f"threshold={SKILL_NUDGE_INTERVAL}\n"
+        f"  → {n_since} events since last skill materialize. CHECK: any "
+        f"closed thread rich enough (≥5 notes, ≥2 insight/move)? If yes → "
+        f"review_thread(thread_id, focus='skills', mode='auto') OR "
+        f"skill_manage(action='patch', ...)."
+    )
+
+
+def auto_review_should_fire(conn: sqlite3.Connection,
+                            session_id: str,
+                            force: bool = False) -> Optional[str]:
+    """Decide whether to fire a background review NOW.
+
+    Returns the thread_id of the richest pending closed thread (≥5 notes,
+    ≥2 insight/move, no prior skill_materialized) if all of:
+      - AUTO_REVIEW_ENABLED is true (skipped when force=True)
+      - skill-nudge counter is at or past SKILL_NUDGE_INTERVAL (skipped
+        when force=True)
+      - a rich pending thread exists
+
+    Otherwise None.
+    """
+    if not force:
+        if not AUTO_REVIEW_ENABLED:
+            return None
+        if SKILL_NUDGE_INTERVAL <= 0:
+            return None
+        if not session_id:
+            return None
+        last_id = _last_reset_event_id(conn, session_id, _SKILL_RESET_KINDS)
+        n_since = _count_events_since(conn, session_id, last_id,
+                                      _SKILL_RESET_KINDS)
+        if n_since < SKILL_NUDGE_INTERVAL:
+            return None
+    return _find_rich_pending_thread(conn)

threadkeeper/process_health.py

@@ -0,0 +1,202 @@
+"""Detection and cleanup of orphaned thread-keeper server processes.
+
+Each Claude client (Code CLI, Desktop, VS Code extension, headless `claude -p`)
+spawns its own thread-keeper subprocess via stdio MCP. When the client dies
+cleanly, its subprocess gets reaped. When the client crashes / is killed -9 /
+loses its parent, the thread-keeper can linger as an orphan: still holding
+file handles, embedding model in RAM, but with no peer ever sending it stdin.
+
+Detection criteria (a process is "orphaned" when ALL hold):
+  1. Process is a threadkeeper.server invocation
+  2. Parent process is gone (ppid is 1/launchd OR ppid doesn't exist)
+  3. Either:
+     - heartbeat_at on its session row is older than `STALE_HEARTBEAT_S`, OR
+     - the process has no session row in `presence` (it never finished
+       bootstrapping)
+
+Cleanup never touches the running parent process itself — only other
+thread-keeper processes that meet the orphan criteria.
+
+Public API:
+  scan() -> list[dict]      # diagnostic snapshot of all mp processes
+  cleanup(dry_run, force) -> dict   # kill orphans
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from typing import Optional
+
+from .db import get_db
+
+
+# Seconds of presence-table silence before we consider a process orphaned.
+STALE_HEARTBEAT_S = 5 * 60
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Process discovery
+# ─────────────────────────────────────────────────────────────────────
+
+def _list_threadkeeper_pids() -> list[dict]:
+    """Find every running threadkeeper.server invocation. Returns rows
+    with pid, ppid, rss_kb, etime_s, full command. Skips disclaimer
+    wrappers (parent shim that exec's the real Python and exits)."""
+    try:
+        r = subprocess.run(
+            ["ps", "-ax", "-o", "pid=,ppid=,rss=,etime=,command="],
+            capture_output=True, text=True, timeout=5,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return []
+    out: list[dict] = []
+    for line in (r.stdout or "").splitlines():
+        if "threadkeeper.server" not in line:
+            continue
+        # Skip the disclaimer shim: its command starts with the
+        # /Applications/Claude.app/Contents/Helpers/disclaimer path and
+        # holds RSS ≈0. We want only the real Python that took its place.
+        if "/Helpers/disclaimer" in line:
+            continue
+        # Tokenize: pid ppid rss etime command...
+        parts = line.split(None, 4)
+        if len(parts) < 5:
+            continue
+        try:
+            pid = int(parts[0])
+            ppid = int(parts[1])
+            rss = int(parts[2])
+        except ValueError:
+            continue
+        etime = parts[3]
+        cmd = parts[4]
+        out.append({
+            "pid": pid,
+            "ppid": ppid,
+            "rss_kb": rss,
+            "etime": etime,
+            "command": cmd,
+        })
+    return out
+
+
+def _pid_alive(pid: int) -> bool:
+    """True if the given pid exists. pid=1 (init/launchd) and pid<=0 return
+    False — we treat init as 'no real parent'."""
+    if pid is None or pid <= 1:
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError):
+        # ProcessLookupError → not alive
+        # PermissionError → it exists but isn't ours — count as alive
+        return isinstance(_sentinel_for_perm_error(pid), bool)
+    except OSError:
+        return False
+
+
+def _sentinel_for_perm_error(pid: int) -> bool:
+    """PermissionError on os.kill(pid, 0) means the pid exists but is owned
+    by another user. We can't probe it, but it IS alive."""
+    return True
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Orphan classification
+# ─────────────────────────────────────────────────────────────────────
+
+def _heartbeat_age_for_pid(conn, pid: int) -> Optional[int]:
+    """Look up presence.heartbeat_at for the session that this pid most
+    likely belongs to. Heuristic: pid embedded in session_id format
+    `s_<pid>_<hex>`. Returns age in seconds, or None if no match."""
+    row = conn.execute(
+        "SELECT heartbeat_at FROM presence "
+        "WHERE session_id LIKE ? "
+        "ORDER BY heartbeat_at DESC LIMIT 1",
+        (f"s_{pid}_%",),
+    ).fetchone()
+    if not row or not row["heartbeat_at"]:
+        return None
+    return int(time.time()) - int(row["heartbeat_at"])
+
+
+def classify(p: dict, conn) -> dict:
+    """Return p augmented with orphan classification. Sets:
+      - `parent_alive` (bool)
+      - `heartbeat_age_s` (int | None)
+      - `is_orphaned` (bool)
+      - `is_self` (bool) — never classify our own pid as orphan
+    """
+    p = dict(p)
+    p["parent_alive"] = _pid_alive(p["ppid"])
+    p["heartbeat_age_s"] = _heartbeat_age_for_pid(conn, p["pid"])
+    p["is_self"] = (p["pid"] == os.getpid())
+
+    if p["is_self"]:
+        p["is_orphaned"] = False
+        p["orphan_reason"] = "self"
+        return p
+
+    if p["parent_alive"]:
+        p["is_orphaned"] = False
+        p["orphan_reason"] = "parent_alive"
+        return p
+
+    # Parent gone. Now check heartbeat freshness.
+    hb = p["heartbeat_age_s"]
+    if hb is None:
+        # No presence row — process either died before bootstrapping or
+        # uses a different session-id format. Treat as orphan to be safe;
+        # if it's a real living process it'll come back next session.
+        p["is_orphaned"] = True
+        p["orphan_reason"] = "parent_gone + no_heartbeat"
+        return p
+    if hb > STALE_HEARTBEAT_S:
+        p["is_orphaned"] = True
+        p["orphan_reason"] = f"parent_gone + heartbeat_age={hb}s > {STALE_HEARTBEAT_S}s"
+        return p
+    p["is_orphaned"] = False
+    p["orphan_reason"] = f"parent_gone but heartbeat fresh ({hb}s)"
+    return p
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Public API
+# ─────────────────────────────────────────────────────────────────────
+
+def scan() -> list[dict]:
+    """Return a list of classified thread-keeper processes."""
+    conn = get_db()
+    procs = _list_threadkeeper_pids()
+    return [classify(p, conn) for p in procs]
+
+
+def cleanup(dry_run: bool = True, force: bool = False) -> dict:
+    """Kill orphaned processes. dry_run=True returns the plan without
+    killing. force=True sends SIGKILL instead of SIGTERM (which gives the
+    process a chance to flush)."""
+    import signal as _sig
+    procs = scan()
+    plan = [p for p in procs if p.get("is_orphaned")]
+    killed: list[int] = []
+    failed: list[dict] = []
+    if not dry_run:
+        sig = _sig.SIGKILL if force else _sig.SIGTERM
+        for p in plan:
+            try:
+                os.kill(p["pid"], sig)
+                killed.append(p["pid"])
+            except (ProcessLookupError, PermissionError) as e:
+                failed.append({"pid": p["pid"], "err": str(e)})
+            except OSError as e:
+                failed.append({"pid": p["pid"], "err": str(e)})
+    return {
+        "all_procs": procs,
+        "orphans": plan,
+        "killed": killed,
+        "failed": failed,
+        "dry_run": dry_run,
+    }

threadkeeper/review_prompts.py

@@ -0,0 +1,207 @@
+"""Self-improvement review prompts.
+
+Adapted from hermes-agent's MEMORY_REVIEW_PROMPT / SKILL_REVIEW_PROMPT
+constants. The "do NOT capture" list is the part that prevents auto-curation
+from harming itself by hardening transient failures into permanent rules.
+
+Used by:
+- review_thread(mode='auto') — spawned background child receives one of these
+  as its prompt and runs through the conversation reading recent notes.
+- review_thread(mode='inline') — foreground agent gets the text back and
+  processes it in the current turn.
+"""
+
+# Rubric-form opener for the review prompts. Hermes Agent v0.12 switched
+# its review fork from free-form "should this update memory/skills?" to
+# rubric-based grading — that change halved their false-negative rate on
+# substantive incidents. We mirror the pattern: 5 yes/no questions, each
+# with a concrete action attached. "Nothing to save." is allowed ONLY
+# when all five answers are No.
+RUBRIC_QUESTIONS = (
+    "RUBRIC — answer each question. ANY \"YES\" answer requires action; "
+    "only ALL-\"NO\" allows the \"Nothing to save.\" stop.\n\n"
+    "  Q1. Did the user state a workflow rule as POLICY "
+    "(\"always do X\", \"next time Y\", \"prefer Path-1 over Path-2 "
+    "when Z\")? Frustration signals (\"stop doing X\", \"this is too "
+    "verbose\") and explicit \"remember this\" count as YES.\n"
+    "      → YES: capture as stated-policy lesson; embed the preference "
+    "verbatim so next session starts already knowing.\n\n"
+    "  Q2. Did a RECOVERY / CLEANUP procedure for flaky infra emerge "
+    "(network reset before tool start, proxy state hygiene, "
+    "zombie-process cleanup, port-reuse wait-loops)?\n"
+    "      → YES: capture as recovery-pattern lesson. The env-specific "
+    "incident becomes ONE worked example inside a rule-shaped lesson, "
+    "NOT the whole content.\n\n"
+    "  Q3. Did a DEBUGGING STRATEGY generalize beyond this specific "
+    "bug (pattern-recognition rules like \"check testID drift before "
+    "chasing logic\", \"3 compounding bugs detection via element-cache "
+    "+ Z-order + fixture mismatch\", \"verify state transition, not "
+    "destination label\")?\n"
+    "      → YES: capture as debugging-pattern lesson.\n\n"
+    "  Q4. Was an EXISTING skill or lesson corrected, missing a step, "
+    "or outdated relative to what just happened?\n"
+    "      → YES: PATCH the existing one BEFORE considering a new "
+    "lesson. New lessons that overlap existing ones pollute the store.\n\n"
+    "  Q5. Did a non-trivial TECHNIQUE / FIX / TOOL-USAGE PATTERN "
+    "emerge that someone else hitting the same class of problem would "
+    "want to know — not the specific bug, the SHAPE of the solution?\n"
+    "      → YES: capture under the appropriate umbrella; prefer "
+    "references/<topic>.md under an existing skill if it fits."
+)
+
+
+# Counter-weight to ANTI_CAPTURE. The original anti-capture clause is
+# strong enough that early calibration data showed shadow children
+# SKIPping 100% of substantive incidents — every real-world fix has
+# *some* env-specific surface, and the children kept classifying the
+# whole episode as env-specific even when the underlying pattern was
+# durable. POSITIVE_EXAMPLES draws the surface/pattern line explicitly.
+POSITIVE_EXAMPLES = (
+    "CAPTURE these even when they emerged in a single incident — the "
+    "FIX/PATTERN is durable even if the failure surface was env-specific:\n"
+    "  • Recovery patterns for flaky infra (network resets before WDA "
+    "start, proxy state hygiene, zombie-process cleanup, port-reuse "
+    "wait-loops). The HOW-TO is generalizable across every future "
+    "instance, not specific to today's test.\n"
+    "  • Debugging-strategy patterns: \"3 compounding bugs detection "
+    "via element-cache + Z-order + fixture mismatch\", \"check testID "
+    "drift before chasing logic\", \"verify state transition, not just "
+    "destination label\". Pattern-recognition rules outlive the bug "
+    "that surfaced them.\n"
+    "  • Workflow rules the user stated as policy (\"on each test "
+    "start, do X\", \"before claiming a fix, verify Y\", \"prefer "
+    "Path-1 over Path-2 when Z\"). Stated policies are first-class "
+    "skill content.\n"
+    "  • iOS/Android testing recovery — WDA + macOS Wi-Fi proxy state, "
+    "XCUITest element-cache invalidation, share-cluster bug "
+    "triangulation, Detox/Maestro selector hierarchies. Class-level "
+    "even when discovered in one suite.\n\n"
+    "KEY DISTINCTION — \"episode env-specific\" vs \"rule env-specific\":\n"
+    "  If the SYMPTOM looked env-specific (Plaid flake, fixture testID "
+    "drift, payout step ordering) but the underlying FIX generalizes "
+    "(always reset network before WDA start; always check for testID "
+    "drift before chasing logic bugs; always make optional/ad-hoc "
+    "fixture steps explicit) — CAPTURE the generalized rule, not the "
+    "incident. Use the incident as ONE illustrative example inside a "
+    "rule-shaped lesson.\n\n"
+    "ANTI_CAPTURE still applies — but only for genuinely transient env "
+    "errors (\"npm i fixed it\", \"reboot fixed it\") with no durable "
+    "rule. If you find yourself writing the verdict \"environment-"
+    "specific E2E debugging — no class-level rule\" but the conversation "
+    "ALSO contains stated policies, recovery procedures, or "
+    "pattern-recognition heuristics — those ARE class-level, capture "
+    "them as a rule lesson with the incident as the worked example."
+)
+
+
+# Shared do-NOT-capture clause. Quoted in both prompts so a foreground agent
+# trying to "save everything" stops at this fence.
+ANTI_CAPTURE = (
+    "Do NOT capture (these become persistent self-imposed constraints that "
+    "bite you later when the environment changes):\n"
+    "  • Environment-dependent failures: missing binaries, fresh-install "
+    "errors, post-migration path mismatches, 'command not found', "
+    "unconfigured credentials, uninstalled packages. The user can fix "
+    "these — they are not durable rules.\n"
+    "  • Negative claims about tools or features ('browser tools do not "
+    "work', 'X tool is broken', 'cannot use Y from execute_code'). These "
+    "harden into refusals the agent cites against itself for months "
+    "after the actual problem was fixed.\n"
+    "  • Session-specific transient errors that resolved before the "
+    "conversation ended. If retrying worked, the lesson is the retry "
+    "pattern, not the original failure.\n"
+    "  • One-off task narratives. A user asking 'summarize today's "
+    "market' or 'analyze this PR' is not a class of work that warrants "
+    "a skill.\n\n"
+    "If a tool failed because of setup state, capture the FIX (install "
+    "command, config step, env var to set) under an existing setup or "
+    "troubleshooting skill — never 'this tool does not work' as a "
+    "standalone constraint."
+)
+
+
+MEMORY_REVIEW_PROMPT = (
+    "Review the closed thread above (use search() or the notes_for_thread "
+    "context below) and consider saving to memory if appropriate.\n\n"
+    "Focus on:\n"
+    "1. Has the user revealed things about themselves — persona, "
+    "preferences, work style, personal details worth remembering?\n"
+    "2. Has the user expressed expectations about how you should "
+    "behave or operate in this kind of task?\n\n"
+    "If something stands out, write it via core_set() for high-priority "
+    "always-on lines OR verbatim_user() for a quoted fragment OR an "
+    "appropriate note() on the source thread. " + ANTI_CAPTURE + "\n\n"
+    "If nothing is worth saving, broadcast 'Nothing to save.' and stop."
+)
+
+
+SKILL_REVIEW_PROMPT = (
+    "Review the closed thread above and materialize any class-level "
+    "lessons.\n\n"
+    "PRIMARY output: a SKILL.md under ~/.claude/skills/<name>/ via "
+    "skill_manage(action='create'|'patch'|'write_file'|'delete'). The "
+    "Skill format is the universal format — Claude Code, Claude "
+    "Desktop, Codex, the Anthropic IDE plugins, and any MCP-aware tool "
+    "consume it. SKILL.md auto-triggers via the frontmatter "
+    "description field, so the right skill loads when relevant — vs. "
+    "an opt-in scan of lessons.md.\n\n"
+    "FALLBACK output (only when target CLI has no skills/ directory — "
+    "Gemini / Copilot / generic MCP clients without a skill loader): "
+    "lesson_append(title, body, summary, source=thread_id) writes into "
+    "~/.threadkeeper/lessons.md. Use this only if the primary path "
+    "isn't available; otherwise the SKILL.md is strictly better.\n\n"
+    + RUBRIC_QUESTIONS + "\n\n"
+    "PREFERENCE ORDER (pick the earliest action that fits):\n"
+    "  1. PATCH an existing skill. If the conversation referenced (or "
+    "the RECENTLY ACTIVE SKILLS block surfaces) an existing skill "
+    "covering the new learning, use skill_manage(action='patch', "
+    "name=..., old_string=..., new_string=...). New skills that "
+    "overlap existing ones pollute the store — patch beats create.\n"
+    "  2. ADD a `references/<topic>.md` under an existing umbrella for "
+    "session-specific detail. Use skill_manage(action='write_file', "
+    "name=..., sub_path='references/<topic>.md', content=...). Keeps "
+    "the parent SKILL.md compact; references load lazily.\n"
+    "  3. CREATE a new class-level umbrella via skill_manage(action="
+    "'create', ...). Name MUST be class-level — never an incident "
+    "codename, PR number, or 'fix-X-today' artifact. If the name only "
+    "makes sense for today's task, fall back to (1) or (2).\n"
+    "  4. DELETE if you discover the consulted skill was a false "
+    "positive (created in error, doesn't actually apply): "
+    "skill_manage(action='delete', name=...). Don't leave wrong "
+    "skills in the store hoping next session ignores them — they "
+    "auto-load via frontmatter and bias future runs.\n\n"
+    "Target shape: CLASS-LEVEL umbrella skills with rich SKILL.md and "
+    "optional references/ directory for session-specific detail — NOT "
+    "a long flat list of narrow one-incident skills.\n\n"
+    "When done, call mark_skill_materialized(thread_id, skill_path) so "
+    "the brief's skill_hint stops firing for this thread.\n\n"
+    + POSITIVE_EXAMPLES + "\n\n"
+    + ANTI_CAPTURE + "\n\n"
+    "STOP CONDITION: \"Nothing to save.\" is only legal when ALL of "
+    "Q1-Q5 above answer No. If even one answers Yes, you must act."
+)
+
+
+COMBINED_REVIEW_PROMPT = (
+    "Review the closed thread above and update two dimensions in one "
+    "pass:\n\n"
+    "  **Memory** — who the user is. Did the user reveal persona, "
+    "preferences, work style, personal details, or expectations about "
+    "how you should operate? If yes, save via core_set / verbatim_user "
+    "/ note as appropriate.\n\n"
+    "  **Skills** — how to handle this class of task. PRIMARY: "
+    "skill_manage(action='create'|'patch'|'write_file'|'delete') → "
+    "~/.claude/skills/<name>/SKILL.md. The Skill format auto-triggers "
+    "via frontmatter description and is consumed by every modern "
+    "agentic CLI (Claude Code/Desktop, Codex CLI/desktop, IDE plugins) "
+    "— strictly better than an opt-in lessons.md scan. FALLBACK: "
+    "lesson_append(...) → ~/.threadkeeper/lessons.md only for CLIs "
+    "without a skills/ directory (Gemini / Copilot / bare MCP).\n\n"
+    + RUBRIC_QUESTIONS + "\n\n"
+    "After any materialization, call mark_skill_materialized("
+    "thread_id, skill_path_or_lessons_md) to close the loop.\n\n"
+    + POSITIVE_EXAMPLES + "\n\n"
+    + ANTI_CAPTURE + "\n\n"
+    "STOP CONDITION: \"Nothing to save.\" is only legal when ALL of "
+    "Q1-Q5 AND both Memory questions above answer No."
+)