@lumenflow/cli 2.9.0 → 2.11.0

package/templates/core/scripts/safe-git.template

@@ -0,0 +1,29 @@
+#!/bin/sh
+#
+# safe-git
+#
+# A wrapper around git that blocks dangerous operations in the LumenFlow environment.
+# Specifically intercepts 'worktree remove' to prevent orphan directories and state corruption.
+# For all other commands, it passes through to the system git.
+#
+
+set -e
+
+# Block 'worktree remove'
+if [ "$1" = "worktree" ] && [ "$2" = "remove" ]; then
+  echo "" >&2
+  echo "=== LUMENFLOW SAFETY BLOCK ===" >&2
+  echo "" >&2
+  echo "BLOCKED: Manual 'git worktree remove' is unsafe in this environment." >&2
+  echo "" >&2
+  echo "REASON: Manual removal leaves orphan directories and corrupts agent state." >&2
+  echo "" >&2
+  echo "USE INSTEAD:" >&2
+  echo "  pnpm wu:done --id <ID>    (To complete a task)" >&2
+  echo "  pnpm wu:cleanup --id <ID> (To discard a task)" >&2
+  echo "==============================" >&2
+  exit 1
+fi
+
+# Pass through to real git
+exec git "$@"

package/templates/vendors/claude/.claude/hooks/pre-compact-checkpoint.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+#
+# pre-compact-checkpoint.sh
+#
+# PreCompact hook - auto-checkpoint + durable recovery marker (WU-1390)
+#
+# Fires before context compaction to:
+# 1. Save a checkpoint with the current WU progress
+# 2. Write a durable recovery file that survives compaction
+#
+# The recovery file is read by session-start-recovery.sh on the next
+# session start (after compact, resume, or clear) to restore context.
+#
+# Exit codes:
+#   0 = Always allow (cannot block compaction)
+#
+# Uses python3 for JSON parsing (consistent with other hooks)
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  REPO_PATH="$CLAUDE_PROJECT_DIR"
+else
+  REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [[ -z "$REPO_PATH" ]]; then
+    exit 0
+  fi
+fi
+
+# Read JSON input from stdin
+INPUT=$(cat)
+
+# Parse trigger from hook input (defensive - default to "auto")
+# PreCompact provides: { "trigger": "manual" | "auto" }
+TRIGGER=$(python3 -c "
+import json
+import sys
+try:
+    data = json.loads('''$INPUT''')
+    trigger = data.get('trigger', 'auto')
+    print(trigger if trigger else 'auto')
+except:
+    print('auto')
+" 2>/dev/null || echo "auto")
+
+# Get WU ID from worktree context (wu:status --json)
+# Location.worktreeWuId is set when in a worktree
+WU_ID=$(pnpm wu:status --json 2>/dev/null | python3 -c "
+import json
+import sys
+try:
+    data = json.load(sys.stdin)
+    location = data.get('location', {})
+    wu_id = location.get('worktreeWuId') or ''
+    print(wu_id)
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Only proceed if we have a WU ID (working in a worktree)
+if [[ -n "$WU_ID" ]]; then
+  # Save checkpoint with pre-compact trigger
+  # Note: This may fail if CLI not built, but that's OK - recovery file is more important
+  pnpm mem:checkpoint "Auto: pre-${TRIGGER}-compaction" --wu "$WU_ID" --trigger "pre-compact" --quiet 2>/dev/null || true
+
+  # Write durable recovery marker (survives compaction)
+  # This is the key mechanism - file persists and is read by session-start-recovery.sh
+  RECOVERY_DIR="${REPO_PATH}/.lumenflow/state"
+  RECOVERY_FILE="${RECOVERY_DIR}/recovery-pending-${WU_ID}.md"
+
+  mkdir -p "$RECOVERY_DIR"
+
+  # Generate recovery context using mem:recover
+  # The --quiet flag outputs only the recovery context without headers
+  pnpm mem:recover --wu "$WU_ID" --quiet > "$RECOVERY_FILE" 2>/dev/null || {
+    # Fallback minimal recovery if mem:recover fails
+    cat > "$RECOVERY_FILE" << EOF
+# POST-COMPACTION RECOVERY
+
+You are resuming work after context compaction. Your previous context was lost.
+**WU:** ${WU_ID}
+
+## Next Action
+Run \`pnpm wu:spawn --id ${WU_ID}\` to spawn a fresh agent with full context.
+EOF
+  }
+
+  # Output brief warning to stderr (may be compacted away, but recovery file persists)
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "⚠️  COMPACTION: Checkpoint saved for ${WU_ID}" >&2
+  echo "Recovery context: ${RECOVERY_FILE}" >&2
+  echo "Next: pnpm wu:spawn --id ${WU_ID}" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+fi
+
+# Always exit 0 - cannot block compaction
+exit 0

package/templates/vendors/claude/.claude/hooks/session-start-recovery.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+#
+# session-start-recovery.sh
+#
+# SessionStart hook - check for pending recovery and inject context (WU-1390)
+#
+# Fires after session start (on compact, resume, or clear) to:
+# 1. Check for recovery-pending-*.md files written by pre-compact-checkpoint.sh
+# 2. Display the recovery context to the agent
+# 3. Remove the recovery file (one-time recovery)
+#
+# This completes the durable recovery pattern:
+#   PreCompact writes file → SessionStart reads and deletes it
+#
+# Exit codes:
+#   0 = Always allow (informational hook)
+#
+
+set -euo pipefail
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+  REPO_PATH="$CLAUDE_PROJECT_DIR"
+else
+  REPO_PATH=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [[ -z "$REPO_PATH" ]]; then
+    exit 0
+  fi
+fi
+
+RECOVERY_DIR="${REPO_PATH}/.lumenflow/state"
+
+# Check if recovery directory exists
+if [[ ! -d "$RECOVERY_DIR" ]]; then
+  exit 0
+fi
+
+# Find any pending recovery files
+FOUND_RECOVERY=false
+
+for recovery_file in "$RECOVERY_DIR"/recovery-pending-*.md; do
+  # Check if glob matched any files (bash glob returns literal pattern if no match)
+  [[ -f "$recovery_file" ]] || continue
+
+  FOUND_RECOVERY=true
+
+  # Extract WU ID from filename for display
+  WU_ID=$(basename "$recovery_file" | sed 's/recovery-pending-\(.*\)\.md/\1/')
+
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "⚠️  POST-COMPACTION RECOVERY DETECTED" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "" >&2
+
+  # Display the recovery context
+  cat "$recovery_file" >&2
+
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "" >&2
+
+  # Remove after displaying (one-time recovery)
+  rm -f "$recovery_file"
+done
+
+# Additional context if recovery was displayed
+if [[ "$FOUND_RECOVERY" == "true" ]]; then
+  echo "IMPORTANT: Your context was compacted. Review the recovery info above." >&2
+  echo "Recommended: Run 'pnpm wu:spawn --id $WU_ID' for fresh full context." >&2
+  echo "" >&2
+fi
+
+exit 0

package/templates/vendors/claude/.claude/settings.json.template

@@ -45,5 +45,47 @@
       "Bash(/usr/bin/git worktree prune *)"
     ],
     "disableBypassPermissionsMode": "disable"
+  },
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-compact-checkpoint.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-recovery.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-recovery.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start-recovery.sh"
+          }
+        ]
+      }
+    ]
   }
 }

package/templates/vendors/claude/.claude/skills/context-management/SKILL.md.template

@@ -1,7 +1,7 @@
 ---
 name: context-management
 description: Session checkpoint patterns, output bypass for large results, when to spawn fresh sub-agents. Use for long-running sessions, context exhaustion, or agent coordination.
-version: 1.3.0
+version: 1.4.0
 source: docs/04-operations/_frameworks/lumenflow/agent/onboarding/agent-invocation-guide.md
 source_sections: Context Tiers, Session Management, Wave Orchestration
 last_updated: {{DATE}}
@@ -76,16 +76,33 @@ pnpm mem:ready --wu WU-123  # Shows pending work
 pnpm mem:inbox --wu WU-123  # Check signals from other agents
 ```
 
-### Optional: Pre-Clear Checkpoint Hook
+### Durable Recovery Pattern (WU-1390/1394)
 
-If your client supports hooks, add a pre-clear/pre-compaction hook that runs:
+LumenFlow implements automatic recovery hooks that preserve context across compaction:
+
+**Hook Files** (scaffolded by `lumenflow init --client claude`):
+
+- `.claude/hooks/pre-compact-checkpoint.sh` — PreCompact hook: saves checkpoint + writes recovery file
+- `.claude/hooks/session-start-recovery.sh` — SessionStart hook: reads recovery file on compact/resume/clear
+
+**How It Works:**
+
+1. **Before compaction**: PreCompact hook writes `.lumenflow/state/recovery-pending-WU-XXX.md`
+2. **After session start**: SessionStart hook reads + displays recovery context, then deletes the file
+3. **Recovery file persists** through compaction — this is the durable part
+
+**Manual Recovery:**
 
 ```bash
-pnpm mem:checkpoint "Pre-clear: <summary>" --wu WU-XXX --trigger pre-clear
+# Generate recovery context manually (if hooks didn't fire)
+pnpm mem:recover --wu WU-XXX
+
+# Generate spawn prompt with full context
+pnpm wu:spawn --id WU-XXX
 ```
 
-This is a safety net for when humans forget to checkpoint. It does **not** replace the
-spawn-fresh protocol; still exit and spawn a new agent after `/clear`.
+**Important**: The recovery hooks are a safety net. The recommended approach is still to spawn
+a fresh agent before compaction rather than relying on post-compaction recovery.
 
 ## Output Bypass Pattern