continuous-improvement 3.1.0 → 3.9.1

package/plugins/continuous-improvement/hooks/gateguard.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * Runtime PreToolUse gateguard hook.
+ *
+ * Stdin  : JSON { tool_name, tool_input }
+ * Stdout : JSON { decision: "allow" | "block", reason?: string }
+ * Exit   : 0 always (decision is in stdout, fail-open on parse error).
+ *
+ * Three-stage gate per skills/gateguard.md:
+ * - DENY  : first mutating tool call per file, with fact-list reason
+ * - FORCE : agent presents facts (model-side; out of band)
+ * - ALLOW : retry once `_gateguard_facts_presented: true` is set or the
+ *           per-file marker is recorded in session state
+ *
+ * Read-only and exploratory tools (Read, Grep, Glob, routine Bash) bypass
+ * unconditionally. Destructive Bash gates EVERY call, not just first.
+ *
+ * V1 honest limitations (see src/lib/gateguard-state.mts header):
+ *   honor-system flag, state-file deletion, parallel-hook race.
+ *
+ * MultiEdit handling (V1): gates on edits[0].file_path only. Per-file
+ * batching is not implemented — TODO: extend to gate every entry in
+ * edits[]. Tracked in issue #106 acceptance criteria item 5.
+ */
+import { readFileSync } from "node:fs";
+import { isCapReached, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
+const TOOL_ROUTE = {
+    Read: "allow",
+    Grep: "allow",
+    Glob: "allow",
+    LS: "allow",
+    NotebookRead: "allow",
+    Write: "mutating-file",
+    Edit: "mutating-file",
+    MultiEdit: "mutating-file",
+    NotebookEdit: "mutating-file",
+    Bash: "allow",
+};
+const DESTRUCTIVE_PATTERNS = [
+    "rm -rf",
+    "rm -fr",
+    "git reset --hard",
+    "git push --force",
+    "git push -f",
+    "--force-with-lease",
+    "git branch -D",
+    "drop table",
+    "drop database",
+    "drop schema",
+    "truncate ",
+    "mkfs",
+    "dd if=",
+    "format ",
+    "rmdir /s",
+    "del /f /q",
+    "del /q /f",
+    "Remove-Item -Recurse",
+    "Remove-Item -Force",
+];
+function isDestructiveBash(command) {
+    const lower = command.toLowerCase();
+    return DESTRUCTIVE_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
+}
+function classifyTool(toolName, toolInput) {
+    const route = TOOL_ROUTE[toolName] ?? "allow";
+    if (route !== "allow")
+        return route;
+    if (toolName === "Bash" && typeof toolInput.command === "string") {
+        if (isDestructiveBash(toolInput.command))
+            return "destructive-bash";
+    }
+    return "allow";
+}
+function extractFilePath(toolInput) {
+    if (typeof toolInput.file_path === "string")
+        return toolInput.file_path;
+    // MultiEdit V1: first edit's file_path is the canonical key.
+    if (Array.isArray(toolInput.edits) && toolInput.edits.length > 0) {
+        const first = toolInput.edits[0];
+        if (first && typeof first.file_path === "string")
+            return first.file_path;
+    }
+    if (typeof toolInput.command === "string")
+        return toolInput.command;
+    return "";
+}
+function buildMutatingFileReason(toolName, filePath) {
+    return [
+        `Before ${toolName === "Write" ? "creating" : "editing"} ${filePath || "<unknown>"}, present these facts:`,
+        "",
+        "  1. List ALL files that import/require this file (use Grep)",
+        "  2. List the public functions/classes affected by this change",
+        "  3. If this file reads/writes data files, show field names, structure, and date format",
+        "  4. Quote the user's current instruction verbatim",
+        "",
+        "After presenting the facts, retry with `_gateguard_facts_presented: true` in tool_input,",
+        "or with the same file_path after a previous clearance has been recorded for this session.",
+    ].join("\n");
+}
+function buildDestructiveBashReason(command) {
+    return [
+        `Destructive command requested: ${command}`,
+        "",
+        "  1. List ALL files/data this command will modify or delete",
+        "  2. Write a one-line rollback procedure",
+        "  3. Quote the user's current instruction verbatim",
+        "",
+        "Destructive Bash gates EVERY call — clearance is not cached.",
+    ].join("\n");
+}
+function buildCapReachedReason() {
+    return [
+        "Gateguard session clearance cap reached (50 distinct files).",
+        "Start a new Claude Code session to reset the gate. The cap exists to bound",
+        "stuck-loop or rogue-agent clearance from compounding within a single session.",
+    ].join("\n");
+}
+function emit(decision) {
+    process.stdout.write(`${JSON.stringify(decision)}\n`);
+    process.exit(0);
+}
+function main() {
+    let raw = "";
+    try {
+        raw = readFileSync(0, "utf8");
+    }
+    catch {
+        emit({ decision: "allow" });
+        return;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        emit({ decision: "allow" }); // fail-open
+        return;
+    }
+    const toolName = typeof payload.tool_name === "string" ? payload.tool_name : "";
+    const toolInput = payload.tool_input ?? {};
+    const gate = classifyTool(toolName, toolInput);
+    if (gate === "allow") {
+        emit({ decision: "allow" });
+        return;
+    }
+    if (gate === "destructive-bash") {
+        const cmd = typeof toolInput.command === "string" ? toolInput.command : "";
+        emit({ decision: "block", reason: buildDestructiveBashReason(cmd) });
+        return;
+    }
+    // mutating-file
+    const sessionDir = resolveSessionDir();
+    const state = loadState(sessionDir);
+    const filePath = extractFilePath(toolInput);
+    const factsFlagged = toolInput._gateguard_facts_presented === true;
+    const alreadyCleared = filePath !== "" && filePath in state.cleared_files;
+    if (!factsFlagged && !alreadyCleared) {
+        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePath) });
+        return;
+    }
+    if (factsFlagged && !alreadyCleared) {
+        if (isCapReached(state)) {
+            emit({ decision: "block", reason: buildCapReachedReason() });
+            return;
+        }
+        if (filePath !== "") {
+            saveState(sessionDir, markFileCleared(state, filePath));
+        }
+    }
+    emit({ decision: "allow" });
+}
+main();

package/plugins/continuous-improvement/hooks/hooks.json

@@ -0,0 +1,65 @@
+{
+  "description": "Gateguard fact-forcing PreToolUse, observation, session lifecycle, and 3-section-close discipline hooks for continuous-improvement.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gateguard.mjs\"",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/three-section-close.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/continuous-improvement/hooks/observe.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# observe.sh — Mulahazah PreToolUse/PostToolUse observation hook.
+#
+# Two-phase design:
+#   1. PREFERRED: exec the Node observer (bin/observe.mjs) which captures the
+#      rich event schema (tool_input.command for Bash, file_path for Edit/
+#      Write/Read, tool_output) without depending on jq.
+#   2. FALLBACK: if either node is missing OR the Node observer file is not
+#      installed alongside this script, fall through to the in-bash thin-
+#      schema path below. The fallback preserves prior behavior so an
+#      operator who never re-runs `npx continuous-improvement install` is
+#      no worse off than today.
+#
+# Always exits 0 — never blocks the Claude session.
+# Usage: echo '<hook_json>' | observe.sh
+
+trap 'exit 0' EXIT ERR INT TERM
+
+# Phase 1 — try the Node observer. The shim copies bin/observe.mjs and
+# lib/observe-event.mjs alongside this script under ${HOME}/.claude/instincts/
+# preserving the bin/ + lib/ subdirectory layout so the relative import
+# resolves: observe.mjs lives at .../instincts/bin/observe.mjs, the imported
+# observe-event.mjs at .../instincts/lib/observe-event.mjs.
+NODE_OBSERVER="$(dirname "${BASH_SOURCE[0]}")/bin/observe.mjs"
+if [[ -f "$NODE_OBSERVER" ]] && command -v node &>/dev/null; then
+  exec node "$NODE_OBSERVER"
+fi
+
+# Phase 2 — bash fallback (thin schema; preserved for back-compat).
+INSTINCTS_DIR="${HOME}/.claude/instincts"
+
+# ---------------------------------------------------------------------------
+# Read stdin (hook payload) — single read for performance
+# ---------------------------------------------------------------------------
+INPUT="$(cat)"
+[[ -z "$INPUT" ]] && exit 0
+
+# ---------------------------------------------------------------------------
+# Parse hook payload — use jq if available, otherwise basic extraction
+#
+# When jq is missing, observation rows lack tool_input/tool_output, which
+# defeats the auto-instinct pipeline. Emit a one-shot stderr warning per
+# project so the operator notices at the next session start instead of
+# discovering the gap weeks later. The marker file makes it idempotent.
+# ---------------------------------------------------------------------------
+if command -v jq &>/dev/null; then
+  read -r TOOL_NAME SESSION_ID HAS_OUTPUT INPUT_JSON OUTPUT_JSON <<< "$(
+    printf '%s' "$INPUT" | jq -r '
+      (.tool_name // ""),
+      (.session_id // ""),
+      (if has("tool_output") then "yes" else "no" end),
+      ((.tool_input // {} | tostring) | .[0:500]),
+      ((.tool_output // {} | tostring) | .[0:200])
+    ' | paste - - - - -
+  )"
+else
+  # One-shot stderr warning per HOME so the operator learns the constraint.
+  # Marker lives next to instincts/ (not inside it) so it never collides with
+  # tests or analysis loops that iterate INSTINCTS_DIR for project-hash dirs.
+  JQ_WARN_MARKER="${HOME}/.claude/.continuous-improvement-jq-warned"
+  if [[ ! -f "$JQ_WARN_MARKER" ]]; then
+    mkdir -p "${HOME}/.claude" 2>/dev/null
+    printf '[continuous-improvement] jq not found on PATH — observe.sh is using thin-schema fallback. Install jq to enable auto-instinct detection (winget install jqlang.jq | brew install jq | apt install jq). This warning is one-shot per host.\n' >&2
+    : > "$JQ_WARN_MARKER"
+  fi
+  # Fallback: extract tool_name with basic pattern matching
+  TOOL_NAME="$(printf '%s' "$INPUT" | sed -n 's/.*"tool_name" *: *"\([^"]*\)".*/\1/p' | head -1)"
+  SESSION_ID="$(printf '%s' "$INPUT" | sed -n 's/.*"session_id" *: *"\([^"]*\)".*/\1/p' | head -1)"
+  HAS_OUTPUT="no"
+  printf '%s' "$INPUT" | grep -q '"tool_output"' && HAS_OUTPUT="yes"
+  INPUT_JSON="$(printf '%s' "$INPUT" | head -c 500)"
+  OUTPUT_JSON=""
+fi
+
+[[ -z "$TOOL_NAME" ]] && exit 0
+
+# Determine event type
+if [[ "$HAS_OUTPUT" == "yes" ]]; then
+  EVENT="tool_complete"
+else
+  EVENT="tool_start"
+fi
+
+# ---------------------------------------------------------------------------
+# Project detection
+# ---------------------------------------------------------------------------
+PROJECT_ROOT=""
+
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -d "${CLAUDE_PROJECT_DIR}" ]]; then
+  PROJECT_ROOT="${CLAUDE_PROJECT_DIR}"
+fi
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="global"
+fi
+
+# ---------------------------------------------------------------------------
+# Compute project hash and name
+# ---------------------------------------------------------------------------
+PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
+PROJECT_NAME="$(basename "${PROJECT_ROOT%.git}")"
+
+# ---------------------------------------------------------------------------
+# Directory setup
+# ---------------------------------------------------------------------------
+PROJECT_DIR="${INSTINCTS_DIR}/${PROJECT_HASH}"
+OBS_FILE="${PROJECT_DIR}/observations.jsonl"
+
+[[ -d "$PROJECT_DIR" ]] || mkdir -p "$PROJECT_DIR"
+
+# ---------------------------------------------------------------------------
+# Rotate observations.jsonl at 10,000 lines
+# ---------------------------------------------------------------------------
+if [[ -f "$OBS_FILE" ]]; then
+  LINE_COUNT="$(wc -l < "$OBS_FILE")"
+  if (( LINE_COUNT >= 10000 )); then
+    mv "$OBS_FILE" "${PROJECT_DIR}/observations.$(date -u +"%Y-%m-%d-%H%M%S").jsonl"
+    
+    # Clean up old archives - keep only 10 most recent
+    ls -t "${PROJECT_DIR}"/observations.*.jsonl 2>/dev/null | tail -n +11 | xargs -r rm -f
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Append JSONL observation line
+# ---------------------------------------------------------------------------
+TS="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+if command -v jq &>/dev/null; then
+  printf '%s\n' "$(jq -cn \
+    --arg ts "$TS" \
+    --arg event "$EVENT" \
+    --arg session "$SESSION_ID" \
+    --arg tool "$TOOL_NAME" \
+    --arg input_summary "$INPUT_JSON" \
+    --arg output_summary "$OUTPUT_JSON" \
+    --arg project_id "$PROJECT_HASH" \
+    --arg project_name "$PROJECT_NAME" \
+    '{ts:$ts,event:$event,session:$session,tool:$tool,input_summary:$input_summary,output_summary:$output_summary,project_id:$project_id,project_name:$project_name}')" \
+    >> "$OBS_FILE"
+else
+  # Fallback: manual JSON construction
+  printf '{"ts":"%s","event":"%s","session":"%s","tool":"%s","project_id":"%s","project_name":"%s"}\n' \
+    "$TS" "$EVENT" "$SESSION_ID" "$TOOL_NAME" "$PROJECT_HASH" "$PROJECT_NAME" \
+    >> "$OBS_FILE"
+fi
+
+# ---------------------------------------------------------------------------
+# Write project.json if new project
+# ---------------------------------------------------------------------------
+PROJECT_JSON="${PROJECT_DIR}/project.json"
+if [[ ! -f "$PROJECT_JSON" ]]; then
+  if command -v jq &>/dev/null; then
+    jq -n \
+      --arg id "$PROJECT_HASH" \
+      --arg name "$PROJECT_NAME" \
+      --arg root "$PROJECT_ROOT" \
+      --arg created_at "$TS" \
+      '{id:$id,name:$name,root:$root,created_at:$created_at}' \
+      > "$PROJECT_JSON"
+  else
+    printf '{"id":"%s","name":"%s","root":"%s","created_at":"%s"}\n' \
+      "$PROJECT_HASH" "$PROJECT_NAME" "$PROJECT_ROOT" "$TS" \
+      > "$PROJECT_JSON"
+  fi
+fi
+
+exit 0

package/plugins/continuous-improvement/hooks/session.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# session.sh — SessionStart/SessionEnd hook for continuous-improvement
+# SessionStart: loads instincts and prints status
+# SessionEnd: prompts reflection
+# Always exits 0 — never blocks the session
+trap 'exit 0' EXIT ERR INT TERM
+
+INSTINCTS_DIR="${HOME}/.claude/instincts"
+
+# Read stdin
+INPUT="$(cat)"
+[[ -z "$INPUT" ]] && exit 0
+
+# ---------------------------------------------------------------------------
+# Detect event type from hook context
+# ---------------------------------------------------------------------------
+# SessionStart hooks receive no tool_name, SessionEnd hooks may vary.
+# We detect based on the hook_type field or the calling context.
+EVENT_TYPE=""
+if command -v jq &>/dev/null; then
+  EVENT_TYPE="$(printf '%s' "$INPUT" | jq -r '.hook_type // .event_type // "unknown"' 2>/dev/null)"
+else
+  if printf '%s' "$INPUT" | grep -q '"SessionStart"'; then
+    EVENT_TYPE="SessionStart"
+  elif printf '%s' "$INPUT" | grep -q '"SessionEnd"'; then
+    EVENT_TYPE="SessionEnd"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Project detection (same as observe.sh)
+# ---------------------------------------------------------------------------
+PROJECT_ROOT=""
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" && -d "${CLAUDE_PROJECT_DIR}" ]]; then
+  PROJECT_ROOT="${CLAUDE_PROJECT_DIR}"
+fi
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+fi
+if [[ -z "$PROJECT_ROOT" ]]; then
+  PROJECT_ROOT="global"
+fi
+
+PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
+PROJECT_DIR="${INSTINCTS_DIR}/${PROJECT_HASH}"
+
+# ---------------------------------------------------------------------------
+# SessionStart: count observations and instincts, print brief status
+# ---------------------------------------------------------------------------
+if [[ "$EVENT_TYPE" == "SessionStart" || "$EVENT_TYPE" == "unknown" ]]; then
+  OBS_COUNT=0
+  INSTINCT_COUNT=0
+
+  OBS_FILE="${PROJECT_DIR}/observations.jsonl"
+  if [[ -f "$OBS_FILE" ]]; then
+    OBS_COUNT="$(wc -l < "$OBS_FILE" 2>/dev/null || echo 0)"
+  fi
+
+  # Count yaml files in project + global
+  for dir in "$PROJECT_DIR" "${INSTINCTS_DIR}/global"; do
+    if [[ -d "$dir" ]]; then
+      count="$(find "$dir" -maxdepth 1 -name '*.yaml' 2>/dev/null | wc -l)"
+      INSTINCT_COUNT=$((INSTINCT_COUNT + count))
+    fi
+  done
+
+  # Determine level
+  LEVEL="CAPTURE"
+  if (( OBS_COUNT >= 20 )) || (( INSTINCT_COUNT > 0 )); then
+    LEVEL="ANALYZE"
+  fi
+
+  # Check for high-confidence instincts
+  if (( INSTINCT_COUNT > 0 )); then
+    for dir in "$PROJECT_DIR" "${INSTINCTS_DIR}/global"; do
+      if [[ -d "$dir" ]]; then
+        for f in "$dir"/*.yaml; do
+          [[ -f "$f" ]] || continue
+          conf="$(grep '^confidence:' "$f" 2>/dev/null | head -1 | sed 's/confidence: *//')"
+          if [[ -n "$conf" ]]; then
+            # Compare as integer (multiply by 100) using awk for portability
+            int_conf="$(printf '%s' "$conf" | awk '{printf "%.0f", $1 * 100}')"
+            if [[ -n "$int_conf" ]] && (( int_conf >= 70 )); then
+              LEVEL="AUTO-APPLY"
+              break 2
+            elif (( int_conf >= 50 )); then
+              LEVEL="SUGGEST"
+            fi
+          fi
+        done
+      fi
+    done
+  fi
+
+  # Write status to stderr (visible in hook output, not blocking)
+  echo "[continuous-improvement] Level: ${LEVEL} | Observations: ${OBS_COUNT} | Instincts: ${INSTINCT_COUNT}" >&2
+fi
+
+# ---------------------------------------------------------------------------
+# SessionEnd: remind to reflect
+# ---------------------------------------------------------------------------
+if [[ "$EVENT_TYPE" == "SessionEnd" ]]; then
+  echo "[continuous-improvement] Session ending. Run /continuous-improvement to reflect and capture learnings." >&2
+fi
+
+exit 0