flonat-research 0.1.0

package/hooks/context-monitor.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+import os, sys
+_cfg = os.path.expanduser("~/.config/task-mgmt/path")
+if not os.path.exists(_cfg) or not os.path.exists(open(_cfg).read().strip()): sys.exit(0)
+TASK_MGMT = open(_cfg).read().strip()
+"""context-monitor.py
+PostToolUse hook — tracks tool call count as a heuristic for context usage.
+
+Fires on Bash|Task tool calls. Uses tool-call counting as a proxy for context
+window consumption (150 tool calls ~ 100% context).
+
+Three thresholds:
+- 60% (~90 calls): Info — suggest saving key state
+- 80% (~120 calls): Warning — auto-compact approaching
+- 90% (~135 calls): Critical — complete current task
+
+Each warning fires once per session. 60s throttle below warning level.
+Outputs as systemMessage (non-blocking).
+"""
+
+import hashlib
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+# --- Configuration ---
+MAX_TOOL_CALLS = 150  # Conservative: 150 calls ~ 100% context
+THRESHOLDS = [
+    (0.90, "critical", "Context at ~90%. Complete current task. Run `/context-status` to review preservation state."),
+    (0.80, "warning", "Context at ~80%. Auto-compact approaching. Ensure plan + session log are current."),
+    (0.60, "info", "Context at ~60%. Consider saving key state with `/update-focus` or `/session-log`."),
+]
+THROTTLE_SECONDS = 60  # Minimum seconds between info-level messages
+
+# --- Paths ---
+SESSIONS_BASE = Path.home() / ".claude" / "sessions"
+
+
+def project_hash() -> str:
+    """Deterministic hash of the project directory."""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    return hashlib.sha256(project_dir.encode()).hexdigest()[:12]
+
+
+def session_dir() -> Path:
+    """Get or create the session state directory."""
+    d = SESSIONS_BASE / project_hash()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def load_state(sdir: Path) -> dict:
+    """Load the monitor state file, or return defaults."""
+    state_file = sdir / "context-monitor-state.json"
+    if state_file.is_file():
+        try:
+            return json.loads(state_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {"tool_calls": 0, "fired": [], "last_message_time": 0}
+
+
+def save_state(sdir: Path, state: dict) -> None:
+    """Persist monitor state."""
+    state_file = sdir / "context-monitor-state.json"
+    state_file.write_text(json.dumps(state, indent=2), encoding="utf-8")
+
+
+def main():
+    hook_input = json.loads(sys.stdin.read())
+
+    sdir = session_dir()
+    state = load_state(sdir)
+
+    # Increment call count
+    state["tool_calls"] = state.get("tool_calls", 0) + 1
+    count = state["tool_calls"]
+    pct = count / MAX_TOOL_CALLS
+
+    fired = set(state.get("fired", []))
+    now = time.time()
+    last_msg = state.get("last_message_time", 0)
+
+    message = None
+
+    for threshold, level, msg in THRESHOLDS:
+        if pct >= threshold and level not in fired:
+            message = msg
+            fired.add(level)
+            state["last_message_time"] = now
+            break
+
+    # Throttle: don't emit info-level messages more than once per THROTTLE_SECONDS
+    if message and "info" in fired and len(fired) == 1:
+        if (now - last_msg) < THROTTLE_SECONDS and last_msg > 0:
+            message = None
+
+    state["fired"] = list(fired)
+    save_state(sdir, state)
+
+    if message:
+        output = {"systemMessage": f"[Context Monitor] {message}"}
+        print(json.dumps(output))
+        sys.exit(2)  # Exit code 2 = message visible in transcript
+    else:
+        # Silent — no output needed
+        print(json.dumps({}))
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/postcompact-restore.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+import os, sys
+_cfg = os.path.expanduser("~/.config/task-mgmt/path")
+if not os.path.exists(_cfg) or not os.path.exists(open(_cfg).read().strip()): sys.exit(0)
+TASK_MGMT = open(_cfg).read().strip()
+"""postcompact-restore.py
+SessionStart hook (compact matcher) — restores state after context compression.
+
+Reads the pre-compact-state.json saved by precompact-autosave.py, re-scans
+disk for active plan state, and outputs a formatted restoration message as
+additionalContext so Claude immediately knows where things stand.
+
+Deletes the state file after reading to avoid stale restores.
+"""
+
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+TASK_MGMT = Path(TASK_MGMT)
+LOG_DIR = TASK_MGMT / "log"
+PLANS_DIR = LOG_DIR / "plans"
+FOCUS_FILE = TASK_MGMT / ".context" / "current-focus.md"
+SESSIONS_BASE = Path.home() / ".claude" / "sessions"
+
+
+def project_hash() -> str:
+    """Deterministic hash of the project directory."""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    return hashlib.sha256(project_dir.encode()).hexdigest()[:12]
+
+
+def latest_file(directory: Path, pattern: str = "*.md") -> Path | None:
+    """Return the most recently modified file matching pattern, or None."""
+    if not directory.is_dir():
+        return None
+    files = sorted(directory.glob(pattern), key=lambda f: f.stat().st_mtime, reverse=True)
+    return files[0] if files else None
+
+
+def rescan_active_plan() -> dict | None:
+    """Re-scan disk for the active plan (may have been updated since pre-compact save)."""
+    plan_file = latest_file(PLANS_DIR)
+    if not plan_file:
+        return None
+
+    text = plan_file.read_text(encoding="utf-8", errors="replace")
+    text_lower = text.lower()
+
+    if "completed" in text_lower or "done" in text_lower:
+        return None
+
+    status = "DRAFT"
+    if "approved" in text_lower:
+        status = "APPROVED"
+
+    first_unchecked = None
+    for line in text.splitlines():
+        if re.match(r"\s*-\s*\[\s*\]", line):
+            first_unchecked = line.strip()
+            break
+
+    return {
+        "file": plan_file.name,
+        "status": status,
+        "first_unchecked": first_unchecked,
+    }
+
+
+def format_restoration(state: dict, live_plan: dict | None) -> str:
+    """Build the formatted restoration message."""
+    lines = ["## Post-Compaction State Restoration", ""]
+
+    # Pre-compaction timestamp
+    lines.append(f"**Compacted at:** {state.get('timestamp', 'unknown')}")
+    lines.append(f"**Working directory:** {state.get('cwd', 'unknown')}")
+    lines.append("")
+
+    # Current focus
+    focus = state.get("current_focus_headline")
+    if focus:
+        lines.append("### Current Focus")
+        lines.append(focus)
+        lines.append("")
+
+    # Active plan
+    plan = live_plan or state.get("active_plan")
+    if plan:
+        lines.append("### Active Plan")
+        lines.append(f"- **File:** `log/plans/{plan['file']}`")
+        lines.append(f"- **Status:** {plan['status']}")
+        if plan.get("first_unchecked"):
+            lines.append(f"- **Next step:** {plan['first_unchecked']}")
+        lines.append("")
+
+    # Latest session log
+    log_name = state.get("latest_session_log")
+    if log_name:
+        lines.append(f"### Latest Session Log")
+        lines.append(f"- **File:** `log/{log_name}`")
+        lines.append("")
+
+    # Recent decisions
+    decisions = state.get("recent_decisions", [])
+    if decisions:
+        lines.append("### Recent Decisions (pre-compaction)")
+        for d in decisions:
+            lines.append(f"- {d}")
+        lines.append("")
+
+    # Recovery actions
+    lines.append("### Recovery Actions")
+    lines.append("1. Read the active plan file to restore full implementation context")
+    lines.append("2. Read the latest session log to understand recent progress")
+    lines.append("3. Continue from the next unchecked step in the plan")
+
+    return "\n".join(lines)
+
+
+def main():
+    # Read hook input (unused but consumed from stdin)
+    sys.stdin.read()
+
+    phash = project_hash()
+    state_file = SESSIONS_BASE / phash / "pre-compact-state.json"
+
+    if not state_file.is_file():
+        # No pre-compact state found — nothing to restore
+        sys.exit(0)
+
+    state = json.loads(state_file.read_text(encoding="utf-8"))
+
+    # Re-scan disk for live plan state
+    live_plan = rescan_active_plan()
+
+    # Build restoration message
+    message = format_restoration(state, live_plan)
+
+    # Delete state file after reading
+    state_file.unlink()
+
+    # Output as additionalContext
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": message,
+        }
+    }
+    print(json.dumps(output, ensure_ascii=False))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/precompact-autosave.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+import os, sys
+_cfg = os.path.expanduser("~/.config/task-mgmt/path")
+if not os.path.exists(_cfg) or not os.path.exists(open(_cfg).read().strip()): sys.exit(0)
+TASK_MGMT = open(_cfg).read().strip()
+"""precompact-autosave.py
+PreCompact hook — saves state before context compression.
+
+Two outputs:
+1. Human-readable snapshot → log/{TIMESTAMP}-compact.md  (existing behaviour)
+2. Machine-readable state  → ~/.claude/sessions/{hash}/pre-compact-state.json
+   (new — read back by postcompact-restore.py after compaction)
+"""
+
+import hashlib
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+TASK_MGMT = Path(TASK_MGMT)
+LOG_DIR = TASK_MGMT / "log"
+PLANS_DIR = LOG_DIR / "plans"
+FOCUS_FILE = TASK_MGMT / ".context" / "current-focus.md"
+SESSIONS_BASE = Path.home() / ".claude" / "sessions"
+
+
+def project_hash() -> str:
+    """Deterministic hash of the project directory (same approach as Pedro's)."""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    return hashlib.sha256(project_dir.encode()).hexdigest()[:12]
+
+
+def latest_file(directory: Path, pattern: str = "*.md") -> Path | None:
+    """Return the most recently modified file matching pattern, or None."""
+    if not directory.is_dir():
+        return None
+    files = sorted(directory.glob(pattern), key=lambda f: f.stat().st_mtime, reverse=True)
+    return files[0] if files else None
+
+
+def active_plan() -> dict | None:
+    """Find the latest plan file and extract its status + first unchecked item."""
+    plan_file = latest_file(PLANS_DIR)
+    if not plan_file:
+        return None
+
+    text = plan_file.read_text(encoding="utf-8", errors="replace")
+
+    # Determine status from content markers
+    status = "DRAFT"
+    text_lower = text.lower()
+    if "approved" in text_lower:
+        status = "APPROVED"
+    if "completed" in text_lower or "done" in text_lower:
+        return None  # Skip completed plans
+
+    # Find first unchecked item
+    first_unchecked = None
+    for line in text.splitlines():
+        if re.match(r"\s*-\s*\[\s*\]", line):
+            first_unchecked = line.strip()
+            break
+
+    return {
+        "file": plan_file.name,
+        "status": status,
+        "first_unchecked": first_unchecked,
+    }
+
+
+def current_focus_headline() -> str | None:
+    """Read the first 5 lines of current-focus.md."""
+    if not FOCUS_FILE.is_file():
+        return None
+    lines = FOCUS_FILE.read_text(encoding="utf-8", errors="replace").splitlines()[:5]
+    return "\n".join(lines) if lines else None
+
+
+def recent_decisions(log_file: Path | None) -> list[str]:
+    """Scan last 50 lines of the latest session log for decision patterns."""
+    if not log_file or not log_file.is_file():
+        return []
+
+    lines = log_file.read_text(encoding="utf-8", errors="replace").splitlines()[-50:]
+    pattern = re.compile(r"(Decision:|Decided:|Chose:|decision:|decided:|chose:)", re.IGNORECASE)
+    decisions = []
+    for line in lines:
+        if pattern.search(line):
+            decisions.append(line.strip())
+    return decisions[:10]  # Cap at 10
+
+
+def save_human_snapshot(hook_input: dict, timestamp: str) -> str:
+    """Save the human-readable markdown snapshot (existing behaviour)."""
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+    session_id = hook_input.get("session_id", "unknown")
+    cwd = hook_input.get("cwd", "unknown")
+    trigger = hook_input.get("trigger", "unknown")
+    transcript = hook_input.get("transcript_path", "unknown")
+
+    now_display = datetime.now().strftime("%Y-%m-%d %H:%M")
+    save_file = LOG_DIR / f"{timestamp}-compact.md"
+
+    content = f"""# Auto-save before context compaction
+
+- **Timestamp:** {now_display}
+- **Session:** {session_id}
+- **Working directory:** {cwd}
+- **Trigger:** {trigger}
+
+> This file was auto-generated by the PreCompact hook.
+> Read the session transcript for full context.
+> Transcript: {transcript}
+"""
+    save_file.write_text(content, encoding="utf-8")
+    return save_file.name
+
+
+def save_machine_state(hook_input: dict, timestamp: str) -> Path:
+    """Save machine-readable JSON state for post-compact restoration."""
+    phash = project_hash()
+    state_dir = SESSIONS_BASE / phash
+    state_dir.mkdir(parents=True, exist_ok=True)
+    state_file = state_dir / "pre-compact-state.json"
+
+    log_file = latest_file(LOG_DIR, "*.md")
+    # Skip compact snapshots when finding the latest session log
+    log_files = sorted(LOG_DIR.glob("*.md"), key=lambda f: f.stat().st_mtime, reverse=True)
+    session_log = None
+    for f in log_files:
+        if "-compact" not in f.name:
+            session_log = f
+            break
+
+    plan = active_plan()
+    focus = current_focus_headline()
+    decisions = recent_decisions(session_log)
+
+    state = {
+        "timestamp": timestamp,
+        "session_id": hook_input.get("session_id", "unknown"),
+        "cwd": hook_input.get("cwd", "unknown"),
+        "active_plan": plan,
+        "latest_session_log": session_log.name if session_log else None,
+        "current_focus_headline": focus,
+        "recent_decisions": decisions,
+    }
+
+    state_file.write_text(json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8")
+    return state_file
+
+
+def main():
+    hook_input = json.loads(sys.stdin.read())
+    timestamp = datetime.now().strftime("%Y-%m-%d-%H%M")
+
+    # 1. Human-readable snapshot (existing)
+    snapshot_name = save_human_snapshot(hook_input, timestamp)
+
+    # 2. Machine-readable state (new)
+    state_file = save_machine_state(hook_input, timestamp)
+
+    # Output hook response
+    output = {
+        "systemMessage": (
+            f"Auto-saved pre-compaction snapshot to log/{snapshot_name} "
+            f"and state to {state_file}"
+        )
+    }
+    print(json.dumps(output))
+
+    # Exit code 2 = message visible in transcript
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/promise-checker.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# Skip on non-Mac environments (cloud, mobile)
+source "$(dirname "$0")/resolve-task-mgmt.sh" || exit 0
+# promise-checker.sh
+# Stop hook — catches "performative compliance": Claude says it remembered/noted/saved
+# something but never actually called Edit or Write.
+#
+# Scans the last assistant turn for promise patterns.
+# If promises found without corresponding Edit/Write tool calls → blocks.
+
+INPUT=$(cat)
+
+# Prevent infinite loops
+STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+if [ "$STOP_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# --- Extract the last assistant turn ---
+# Read transcript from the end, collect all lines until we hit a user message.
+# This captures the full turn (multiple assistant messages + tool results).
+LAST_TURN=$(tac "$TRANSCRIPT_PATH" 2>/dev/null | while IFS= read -r line; do
+  MSG_TYPE=$(echo "$line" | jq -r '.type // empty' 2>/dev/null)
+  if [ "$MSG_TYPE" = "user_message" ]; then
+    break
+  fi
+  echo "$line"
+done)
+
+if [ -z "$LAST_TURN" ]; then
+  exit 0
+fi
+
+# --- Check for Edit/Write tool calls in this turn ---
+HAS_WRITE=$(echo "$LAST_TURN" | \
+  jq -r '.content[]? | select(.type == "tool_use") | .name' 2>/dev/null | \
+  grep -qiE '^(Edit|Write|NotebookEdit)$' && echo "yes" || echo "no")
+
+# --- Extract all text content from assistant messages in this turn ---
+TEXT_CONTENT=$(echo "$LAST_TURN" | \
+  jq -r 'select(.type == "assistant_message") | .content[]? | select(.type == "text") | .text' 2>/dev/null)
+
+if [ -z "$TEXT_CONTENT" ]; then
+  exit 0
+fi
+
+# --- Promise patterns ---
+# Phrases where Claude claims to have stored/remembered/noted something,
+# or promises to do so. Case-insensitive matching applied later.
+
+PROMISE_PATTERNS=(
+  # Future promises to store
+  "I'll remember"
+  "I'll note that"
+  "I'll write that down"
+  "I'll save that"
+  "I'll record"
+  "I'll store"
+  "I'll make a note"
+  "I'll add that to"
+  "I'll put that in"
+  "I'll log that"
+  "I'll update.*memory"
+  "I'll update.*context"
+  "I'll update.*MEMORY"
+  "I'll keep that in mind"
+  "let me note that"
+  "let me save"
+  "let me record"
+  "let me write that"
+  # Past claims of having stored
+  "I've noted"
+  "I've recorded"
+  "I've saved that"
+  "I've stored"
+  "I've memorized"
+  "I've written that down"
+  "I've added that"
+  "I've updated.*memory"
+  "I've updated.*MEMORY"
+  "I've updated.*context"
+  "I've logged"
+  "I've made a note"
+  "I've taken note"
+  "I've put that in"
+  # Short forms
+  "^Noted[.!]"
+  "Noted —"
+  "Noted,"
+  "duly noted"
+)
+
+# Build a single regex from patterns
+REGEX=$(printf '%s|' "${PROMISE_PATTERNS[@]}")
+REGEX="${REGEX%|}"  # Remove trailing pipe
+
+# Check for promise patterns (case-insensitive)
+MATCHED=$(echo "$TEXT_CONTENT" | grep -iE "$REGEX" | head -3)
+
+if [ -z "$MATCHED" ]; then
+  # No promises found — all clear
+  exit 0
+fi
+
+# --- Verdict ---
+if [ "$HAS_WRITE" = "no" ]; then
+  # Promises found but no write actions — block!
+  SNIPPET=$(echo "$MATCHED" | head -1 | cut -c1-80)
+  cat <<EOF
+{
+  "decision": "block",
+  "reason": "Promise without action: you said \"${SNIPPET}\" but no Edit/Write tool was called. Actually write it down (MEMORY.md, context file, or wherever appropriate)."
+}
+EOF
+  exit 0
+fi
+
+# Promises found AND write actions exist — all good
+exit 0

package/hooks/protect-source-files.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# Skip on non-Mac environments (cloud, mobile)
+source "$(dirname "$0")/resolve-task-mgmt.sh" || exit 0
+# protect-source-files.sh
+# PreToolUse hook for Edit|Write — prompts confirmation for files outside
+# the current project, ~/.claude/, and the Task Management directory.
+# Soft block (permissionDecision: "ask"), not hard block.
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+
+# If no file path, allow (shouldn't happen but be safe)
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Resolve to absolute paths
+FILE_PATH=$(cd "$(dirname "$FILE_PATH")" 2>/dev/null && echo "$(pwd)/$(basename "$FILE_PATH")" || echo "$FILE_PATH")
+CWD=$(cd "$CWD" 2>/dev/null && pwd || echo "$CWD")
+CLAUDE_DIR="$HOME/.claude"
+
+# Allow: file is inside CWD (logical path)
+if [[ "$FILE_PATH" == "$CWD"/* ]]; then
+  exit 0
+fi
+
+# Allow: file is inside CWD (resolved/physical path, handles symlinks)
+RESOLVED_CWD=$(cd "$CWD" 2>/dev/null && pwd -P || echo "$CWD")
+if [[ "$FILE_PATH" == "$RESOLVED_CWD"/* ]]; then
+  exit 0
+fi
+
+# Allow: file is inside any symlink target reachable from CWD (one level deep)
+# This handles e.g. paper/ -> Overleaf/ where resolved paths differ from CWD
+for LINK in "$CWD"/*/; do
+  if [ -L "${LINK%/}" ]; then
+    LINK_TARGET=$(cd "${LINK%/}" 2>/dev/null && pwd -P || continue)
+    if [[ -n "$LINK_TARGET" ]] && [[ "$FILE_PATH" == "$LINK_TARGET"/* ]]; then
+      exit 0
+    fi
+  fi
+done
+
+# Allow: file is under ~/.claude/ (settings, memory, skills)
+if [[ "$FILE_PATH" == "$CLAUDE_DIR"/* ]]; then
+  exit 0
+fi
+
+# Allow: file is under Task Management directory (context library)
+if [[ "$FILE_PATH" == "$TASK_MGMT"/* ]]; then
+  exit 0
+fi
+
+# Block: skill files outside Task Management (skills are global only)
+if [[ "$FILE_PATH" == */skills/*/SKILL.md ]] && [[ "$FILE_PATH" != "$TASK_MGMT"/skills/* ]]; then
+  cat <<BLOCK
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Skills must be created in Task Management/skills/, not locally. This file would be created at: $FILE_PATH"
+  }
+}
+BLOCK
+  exit 0
+fi
+
+# Outside all known safe zones — ask for confirmation
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "ask",
+    "permissionDecisionReason": "File is outside current project: $FILE_PATH — confirm?"
+  }
+}
+EOF
+
+exit 0