@chrisai/base 2.3.0

package/src/hooks/_template.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+BASE Hook Template — Canonical reference for data surface injection hooks.
+
+THIS IS A TEMPLATE, NOT A RUNNABLE HOOK.
+Copy this file, rename it to {surface}-hook.py, and customize the marked sections.
+
+=== CONTRACT ===
+Every data surface hook MUST follow this contract:
+  1. Reads ONE JSON file from .base/data/{SURFACE_NAME}.json
+  2. Outputs a compact XML-tagged block to stdout
+  3. Wraps output in <{SURFACE_NAME}-awareness> tags
+  4. Includes a BEHAVIOR directive block
+  5. Exits cleanly (exit 0) — never crashes, never blocks
+
+=== DO ===
+  - Read the JSON file using absolute paths (Path(__file__).resolve())
+  - Format a compact summary: IDs, one-line descriptions, grouped by priority/status
+  - Include item count summaries
+  - Include the behavioral directive (passive by default)
+  - Handle missing/empty/malformed files gracefully (output nothing, exit 0)
+  - Keep output compact — hooks fire every prompt, token cost matters
+
+=== DO NOT ===
+  - Never write to any file
+  - Never make network calls
+  - Never import heavy dependencies (sys, json, pathlib ONLY)
+  - Never read multiple data files (one hook = one surface)
+  - Never include full item details in injection (that's what MCP tools are for)
+  - Never include dynamic logic that changes based on time of day, session count, etc.
+
+=== TRIGGERS ===
+Register in .claude/settings.json under UserPromptSubmit:
+  {
+    "type": "command",
+    "command": "python3 /absolute/path/to/.base/hooks/{surface}-hook.py"
+  }
+"""
+
+import sys
+import json
+from pathlib import Path
+
+# ============================================================
+# CONFIGURATION — CUSTOMIZE THIS
+# ============================================================
+
+SURFACE_NAME = "example"  # CHANGE THIS: your surface name (e.g., "active", "backlog")
+
+# ============================================================
+# PATH RESOLUTION — DO NOT CHANGE
+# ============================================================
+
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent           # .base/hooks/ → .base/ → workspace root is parent of .base/
+# Fix: .base/hooks/_template.py → .base/ is parent, workspace root is parent of .base/
+WORKSPACE_ROOT = HOOK_DIR.parent.parent
+DATA_FILE = WORKSPACE_ROOT / ".base" / "data" / f"{SURFACE_NAME}.json"
+
+# ============================================================
+# BEHAVIORAL DIRECTIVE — CUSTOMIZE IF NEEDED
+# ============================================================
+
+BEHAVIOR_DIRECTIVE = f"""BEHAVIOR: This context is PASSIVE AWARENESS ONLY.
+Do NOT proactively mention these items unless:
+  - User explicitly asks (e.g., "what should I work on?", "what's next?")
+  - A deadline is within 24 hours AND user hasn't acknowledged it this session
+For details on any item, use base_get_item("{SURFACE_NAME}", id)."""
+
+
+def main():
+    # --- Read hook input from stdin (Claude Code provides session context) ---
+    try:
+        input_data = json.loads(sys.stdin.read())
+        session_id = input_data.get("session_id", "")
+    except (json.JSONDecodeError, OSError):
+        session_id = ""
+
+    # --- Guard: file must exist ---
+    if not DATA_FILE.exists():
+        sys.exit(0)
+
+    # --- Read and parse JSON ---
+    try:
+        data = json.loads(DATA_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    # ============================================================
+    # ITEM EXTRACTION — CUSTOMIZE THIS
+    # ============================================================
+    # Default expects: { "items": [ { "id": "...", "title": "...", ... }, ... ] }
+    # Adjust the key and field names to match your surface's schema.
+
+    items = data.get("items", [])
+
+    if not items:
+        sys.exit(0)
+
+    # ============================================================
+    # SUMMARY FORMATTING — CUSTOMIZE THIS
+    # ============================================================
+    # Build compact summary lines. Keep it SHORT — one line per item max.
+    # Group by status/priority if your schema supports it.
+    # Example format: "- [ID] Title (status)"
+
+    lines = []
+    for item in items:
+        item_id = item.get("id", "?")
+        title = item.get("title", "untitled")
+        status = item.get("status", "")
+        status_suffix = f" ({status})" if status else ""
+        lines.append(f"- [{item_id}] {title}{status_suffix}")
+
+    # --- Output ---
+    if lines:
+        count = len(items)
+        summary = "\n".join(lines)
+        print(f"""<{SURFACE_NAME}-awareness items="{count}">
+{summary}
+
+{BEHAVIOR_DIRECTIVE}
+</{SURFACE_NAME}-awareness>""")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/src/hooks/active-hook.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+BASE Hook: active-hook.py
+Surface: active (Active work items, projects, and tasks)
+Source: .base/data/active.json
+Output: <active-awareness> compact summary grouped by priority
+"""
+
+import sys
+import json
+from pathlib import Path
+from datetime import date
+
+SURFACE_NAME = "active"
+
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent.parent
+DATA_FILE = WORKSPACE_ROOT / ".base" / "data" / f"{SURFACE_NAME}.json"
+
+BEHAVIOR_DIRECTIVE = f"""BEHAVIOR: This context is PASSIVE AWARENESS ONLY.
+Do NOT proactively mention these items unless:
+  - User explicitly asks (e.g., "what should I work on?", "what's next?")
+  - A deadline is within 24 hours AND user hasn't acknowledged it this session
+For details on any item, use base_get_item("{SURFACE_NAME}", id)."""
+
+PRIORITY_ORDER = ["urgent", "high", "medium", "ongoing", "deferred"]
+
+# Staleness thresholds (days since last update)
+STALE_THRESHOLDS = {
+    "urgent": 3,
+    "high": 5,
+    "medium": 7,
+    "ongoing": 14,
+    "deferred": 30,
+}
+
+
+def days_since_update(item):
+    """Calculate days since last update. Uses 'updated' if present, else 'added'."""
+    ts = item.get("updated") or item.get("added")
+    if not ts:
+        return None
+    try:
+        d = date.fromisoformat(ts[:10])
+        return (date.today() - d).days
+    except (ValueError, TypeError):
+        return None
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, OSError):
+        pass
+
+    if not DATA_FILE.exists():
+        sys.exit(0)
+
+    try:
+        data = json.loads(DATA_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    items = data.get("items", [])
+    if not items:
+        sys.exit(0)
+
+    # Group by priority
+    groups = {}
+    for item in items:
+        p = item.get("priority", "medium")
+        groups.setdefault(p, []).append(item)
+
+    lines = []
+    for priority in PRIORITY_ORDER:
+        group = groups.get(priority, [])
+        if not group:
+            continue
+        lines.append(f"[{priority.upper()}]")
+        for item in group:
+            item_id = item.get("id", "?")
+            title = item.get("title", "untitled")
+            status = item.get("status", "")
+            parts = [f"- [{item_id}] {title}"]
+            if status:
+                parts[0] += f" ({status})"
+            blocked = item.get("blocked")
+            if blocked:
+                parts.append(f"  BLOCKED: {blocked}")
+            deadline = item.get("deadline")
+            if deadline:
+                parts.append(f"  DUE: {deadline}")
+            days = days_since_update(item)
+            threshold = STALE_THRESHOLDS.get(priority, 7)
+            if days is not None:
+                if days >= threshold:
+                    parts.append(f"  STALE: {days}d since update (threshold: {threshold}d)")
+                else:
+                    parts.append(f"  updated: {days}d ago")
+            lines.append("\n".join(parts))
+
+    if lines:
+        count = len(items)
+        summary = "\n".join(lines)
+        print(f"""<{SURFACE_NAME}-awareness items="{count}">
+{summary}
+
+{BEHAVIOR_DIRECTIVE}
+</{SURFACE_NAME}-awareness>""")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/src/hooks/backlog-hook.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+BASE Hook: backlog-hook.py
+Surface: backlog (Future work queue, ideas, and deferred tasks)
+Source: .base/data/backlog.json
+Output: <backlog-awareness> compact summary grouped by priority
+"""
+
+import sys
+import json
+from pathlib import Path
+from datetime import date
+
+SURFACE_NAME = "backlog"
+
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent.parent
+DATA_FILE = WORKSPACE_ROOT / ".base" / "data" / f"{SURFACE_NAME}.json"
+
+BEHAVIOR_DIRECTIVE = f"""BEHAVIOR: This context is PASSIVE AWARENESS ONLY.
+Do NOT proactively mention these items unless:
+  - User explicitly asks (e.g., "what's in the backlog?", "what's queued?")
+  - A review_by date has passed AND user hasn't acknowledged it this session
+For details on any item, use base_get_item("{SURFACE_NAME}", id)."""
+
+PRIORITY_ORDER = ["high", "medium", "low"]
+
+# Staleness thresholds (days since last update)
+STALE_THRESHOLDS = {
+    "high": 7,
+    "medium": 14,
+    "low": 30,
+}
+
+
+def days_since_update(item):
+    """Calculate days since last update. Uses 'updated' if present, else 'added'."""
+    ts = item.get("updated") or item.get("added")
+    if not ts:
+        return None
+    try:
+        d = date.fromisoformat(ts[:10])
+        return (date.today() - d).days
+    except (ValueError, TypeError):
+        return None
+
+
+def main():
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, OSError):
+        pass
+
+    if not DATA_FILE.exists():
+        sys.exit(0)
+
+    try:
+        data = json.loads(DATA_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    items = data.get("items", [])
+    if not items:
+        sys.exit(0)
+
+    # Group by priority
+    groups = {}
+    for item in items:
+        p = item.get("priority", "medium")
+        groups.setdefault(p, []).append(item)
+
+    lines = []
+    for priority in PRIORITY_ORDER:
+        group = groups.get(priority, [])
+        if not group:
+            continue
+        lines.append(f"[{priority.upper()}]")
+        for item in group:
+            item_id = item.get("id", "?")
+            title = item.get("title", "untitled")
+            review_by = item.get("review_by")
+            entry = f"- [{item_id}] {title}"
+            if review_by:
+                entry += f" [review by: {review_by}]"
+            days = days_since_update(item)
+            threshold = STALE_THRESHOLDS.get(priority, 14)
+            if days is not None:
+                if days >= threshold:
+                    entry += f" STALE: {days}d"
+                else:
+                    entry += f" ({days}d ago)"
+            lines.append(entry)
+
+    if lines:
+        count = len(items)
+        summary = "\n".join(lines)
+        print(f"""<{SURFACE_NAME}-awareness items="{count}">
+{summary}
+
+{BEHAVIOR_DIRECTIVE}
+</{SURFACE_NAME}-awareness>""")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/src/hooks/base-pulse-check.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""
+Hook: base-pulse-check.py
+Purpose: BASE workspace health check on session start.
+         Reads .base/STATE.md and workspace.json, calculates drift,
+         injects warning if grooming is overdue.
+Triggers: UserPromptSubmit (session context)
+Output: Workspace health status or groom reminder
+"""
+
+import sys
+import json
+from datetime import datetime
+from pathlib import Path
+
+# Workspace root — find .base/ relative to this hook's location
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent.parent  # .claude/hooks/ -> .claude/ -> workspace
+BASE_DIR = WORKSPACE_ROOT / ".base"
+STATE_FILE = BASE_DIR / "STATE.md"
+MANIFEST_FILE = BASE_DIR / "workspace.json"
+
+
+class WorkspaceState:
+    """Parsed state from STATE.md."""
+    def __init__(self):
+        self.last_groom: datetime | None = None
+        self.next_groom_due: datetime | None = None
+        self.drift_score: int | None = None
+
+
+def parse_state_md(content: str) -> WorkspaceState:
+    """Extract key dates and drift info from STATE.md."""
+    state = WorkspaceState()
+
+    for line in content.split("\n"):
+        if line.startswith("**Last Groom:**"):
+            date_str = line.replace("**Last Groom:**", "").strip()
+            try:
+                state.last_groom = datetime.strptime(date_str, "%Y-%m-%d")
+            except ValueError:
+                pass
+        elif line.startswith("**Next Groom Due:**"):
+            date_str = line.replace("**Next Groom Due:**", "").strip()
+            try:
+                state.next_groom_due = datetime.strptime(date_str, "%Y-%m-%d")
+            except ValueError:
+                pass
+        elif line.startswith("**Drift Score:**"):
+            score_str = line.replace("**Drift Score:**", "").strip().split()[0]
+            try:
+                state.drift_score = int(score_str)
+            except ValueError:
+                pass
+
+    return state
+
+
+def check_file_staleness(workspace_root, manifest):
+    """Check tracked files/directories for staleness based on manifest."""
+    stale_areas = []
+    now = datetime.now()
+
+    areas = manifest.get("areas", {})
+    for area_name, area_config in areas.items():
+        groom_cadence = area_config.get("groom", "weekly")
+        paths = area_config.get("paths", [])
+
+        # Convert cadence to days
+        cadence_days = {"weekly": 7, "bi-weekly": 14, "monthly": 30}.get(groom_cadence, 7)
+
+        for p in paths:
+            full_path = workspace_root / p
+            if full_path.exists():
+                if full_path.is_file():
+                    mtime = datetime.fromtimestamp(full_path.stat().st_mtime)
+                elif full_path.is_dir():
+                    # Use most recent file modification in directory
+                    try:
+                        mtimes = [
+                            f.stat().st_mtime
+                            for f in full_path.iterdir()
+                            if f.is_file() and not f.name.startswith(".")
+                        ]
+                        mtime = datetime.fromtimestamp(max(mtimes)) if mtimes else datetime.fromtimestamp(full_path.stat().st_mtime)
+                    except (OSError, ValueError):
+                        mtime = datetime.fromtimestamp(full_path.stat().st_mtime)
+                else:
+                    continue
+
+                age_days = (now - mtime).days
+                if age_days > cadence_days:
+                    stale_areas.append({
+                        "area": area_name,
+                        "path": p,
+                        "age_days": age_days,
+                        "threshold": cadence_days,
+                        "overdue_by": age_days - cadence_days,
+                    })
+
+    return stale_areas
+
+
+def main():
+    # Skip if BASE is not installed
+    if not BASE_DIR.exists() or not MANIFEST_FILE.exists():
+        # BASE not installed — silent exit
+        sys.exit(0)
+
+    try:
+        with open(MANIFEST_FILE, "r") as f:
+            manifest = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    # Read STATE.md if it exists
+    state = WorkspaceState()
+    if STATE_FILE.exists():
+        try:
+            with open(STATE_FILE, "r") as f:
+                state = parse_state_md(f.read())
+        except OSError:
+            pass
+
+    now = datetime.now()
+    groom_cadence = manifest.get("groom_cadence", "weekly")
+    cadence_days = {"weekly": 7, "bi-weekly": 14, "monthly": 30}.get(groom_cadence, 7)
+
+    # Check if groom is overdue
+    groom_overdue = False
+    days_since_groom = None
+    if state.last_groom:
+        days_since_groom = (now - state.last_groom).days
+        groom_overdue = days_since_groom > cadence_days
+
+    # Check file staleness
+    stale_areas = check_file_staleness(WORKSPACE_ROOT, manifest)
+
+    # Calculate drift score
+    drift_score = sum(area["overdue_by"] for area in stale_areas if area["overdue_by"] > 0)
+
+    # Check CARL hygiene (optional proactive reminder)
+    carl_hygiene_reminder = None
+    carl_hygiene_config = manifest.get("carl_hygiene", {})
+    if carl_hygiene_config.get("proactive", False):
+        hygiene_cadence = {"weekly": 7, "bi-weekly": 14, "monthly": 30}.get(
+            carl_hygiene_config.get("cadence", "monthly"), 30
+        )
+        last_hygiene = carl_hygiene_config.get("last_run")
+        if last_hygiene:
+            try:
+                last_hygiene_date = datetime.strptime(last_hygiene, "%Y-%m-%d")
+                days_since_hygiene = (now - last_hygiene_date).days
+                if days_since_hygiene > hygiene_cadence:
+                    carl_hygiene_reminder = f"CARL hygiene overdue ({days_since_hygiene}d since last run). Run /base:carl-hygiene"
+            except ValueError:
+                carl_hygiene_reminder = "CARL hygiene: last_run date invalid. Run /base:carl-hygiene"
+        else:
+            carl_hygiene_reminder = "CARL hygiene never run. Run /base:carl-hygiene when ready"
+
+        # Also check for staged proposals
+        staging_file = BASE_DIR / "staging.json"
+        if staging_file.exists():
+            try:
+                staging_data = json.loads(staging_file.read_text())
+                pending = [p for p in staging_data.get("proposals", []) if p.get("status") == "pending"]
+                if pending:
+                    carl_hygiene_reminder = (carl_hygiene_reminder or "") + f" | {len(pending)} staged proposals pending"
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    # Build output
+    output_parts = []
+
+    if groom_overdue and days_since_groom is not None and state.last_groom is not None:
+        output_parts.append(
+            f"BASE: Workspace groom overdue by {days_since_groom - cadence_days} days "
+            f"(last groom: {state.last_groom.strftime('%Y-%m-%d')}). "
+            f"Run /base:groom to maintain workspace health."
+        )
+
+    if stale_areas:
+        stale_names = [a["area"] for a in stale_areas]
+        output_parts.append(
+            f"BASE drift score: {drift_score} | Stale areas: {', '.join(stale_names)}"
+        )
+    elif not groom_overdue and state.last_groom is not None:
+        # Everything is fine — minimal output
+        output_parts.append(
+            f"BASE: Drift 0 | Last groom: {state.last_groom.strftime('%Y-%m-%d')} | All areas current"
+        )
+
+    if carl_hygiene_reminder:
+        output_parts.append(carl_hygiene_reminder)
+
+    if output_parts:
+        print(f"""<base-pulse>
+{chr(10).join(output_parts)}
+</base-pulse>""")
+    # Silent if no state yet
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/src/hooks/psmm-injector.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+Hook: psmm-injector.py
+Purpose: Per-Session Meta Memory — inject ephemeral session observations
+         into every prompt so they stay hot in long sessions (1M window).
+
+         Uses a single psmm.json file with session-keyed entries.
+         Each session gets its own array keyed by Claude Code session UUID.
+         Stale sessions are NOT auto-cleaned — that's the operator's job
+         via CARL hygiene / BASE drift detection.
+
+Triggers: UserPromptSubmit
+Output: Current session's PSMM entries as system context, or silent if empty.
+"""
+
+import sys
+import json
+from pathlib import Path
+
+HOOK_DIR = Path(__file__).resolve().parent
+WORKSPACE_ROOT = HOOK_DIR.parent.parent
+PSMM_FILE = WORKSPACE_ROOT / ".base" / "data" / "psmm.json"
+
+
+def main():
+    # Get session_id from hook input
+    try:
+        input_data = json.loads(sys.stdin.read())
+        session_id = input_data.get("session_id", "")
+    except (json.JSONDecodeError, OSError):
+        session_id = ""
+
+    if not session_id or not PSMM_FILE.exists():
+        sys.exit(0)
+
+    try:
+        data = json.loads(PSMM_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        sys.exit(0)
+
+    sessions = data.get("sessions", {})
+    session = sessions.get(session_id)
+
+    if not session or not session.get("entries"):
+        sys.exit(0)
+
+    # Build output from this session's entries
+    entries = session["entries"]
+    lines = []
+    for entry in entries:
+        entry_type = entry.get("type", "NOTE")
+        text = entry.get("text", "")
+        timestamp = entry.get("timestamp", "")
+        lines.append(f"- [{timestamp}] {entry_type}: {text}")
+
+    if lines:
+        created = session.get("created", "unknown")
+        count = len(entries)
+        print(f"""<psmm session="{session_id[:8]}" entries="{count}" created="{created}">
+{chr(10).join(lines)}
+</psmm>""")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()