feed-the-machine 1.1.0 → 1.3.0

package/ftm-state/blackboard/capabilities.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FTM Capabilities Snapshot",
+  "type": "object",
+  "required": ["discovered_at", "expires_at", "capabilities"],
+  "properties": {
+    "discovered_at": { "type": "string", "format": "date-time" },
+    "expires_at": { "type": "string", "format": "date-time" },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type", "verified", "confidence"],
+        "properties": {
+          "name": { "type": "string" },
+          "type": { "type": "string", "enum": ["mcp", "cli", "api", "env", "browser"] },
+          "verified": { "type": "boolean" },
+          "last_verified_at": { "type": "string", "format": "date-time" },
+          "operations_verified": { "type": "array", "items": { "type": "string" } },
+          "path": { "type": "string" },
+          "version": { "type": "string" },
+          "confidence": { "type": "string", "enum": ["verified", "known", "inferred", "unavailable"] }
+        }
+      }
+    }
+  }
+}

package/ftm-upgrade/SKILL.md

@@ -151,3 +151,44 @@ Map `CHECK_FAILED <reason>` codes to user-facing messages:
 **Cache location**: `~/.cache/ftm-brain/version-check`
 **Version file**: `~/.claude/skills/ftm-version.txt`
 **Repo**: `kkudumu/ftm-brain`
+
+## Requirements
+
+- tool: `gh` | required | GitHub CLI for querying releases from kkudumu/ftm-brain
+- reference: `~/.claude/skills/ftm-upgrade/scripts/check-version.sh` | required | version check and cache script
+- reference: `~/.claude/skills/ftm-upgrade/scripts/upgrade.sh` | required | download and install latest release script
+- reference: `~/.claude/skills/ftm-version.txt` | optional | locally installed version number
+
+## Risk
+
+- level: high_write
+- scope: downloads and overwrites skill files in ~/.claude/skills/ on upgrade; changes affect all ftm skill behavior going forward; irreversible without restoring previous version from backup or git
+- rollback: restore from ~/.claude/skills/ backup if one was made before upgrade; or reinstall specific version by downloading an older release tarball
+
+## Approval Gates
+
+- trigger: UPGRADE_AVAILABLE detected | action: show current and latest version with changelog URL, wait for explicit "yes" confirmation before running upgrade.sh
+- trigger: version check during preamble (passive notice pattern) | action: show one-line notice only, do NOT ask for confirmation or interrupt workflow
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: gh not installed | action: report "GitHub CLI not installed" with brew install gh instructions
+- condition: no internet connection | action: report "Cannot reach GitHub. Check internet connection."
+- condition: kkudumu/ftm-brain repo not found | action: report repo not found, suggest verifying access
+- condition: no releases found | action: report "No releases found yet. Check back later."
+- condition: upgrade.sh exits non-zero | action: report failure output, suggest running script manually
+
+## Capabilities
+
+- cli: `gh` | required | GitHub CLI for release queries and download
+- cli: `bash` | required | for running check-version.sh and upgrade.sh
+
+## Event Payloads
+
+### task_completed
+- skill: string — "ftm-upgrade"
+- action: string — "check" | "upgrade" | "already_up_to_date"
+- current_version: string | null — version before upgrade
+- new_version: string | null — version after upgrade (null if no upgrade)
+- status: string — "success" | "failed" | "up_to_date" | "check_failed"

package/hooks/ftm-blackboard-enforcer.sh

@@ -1,10 +1,13 @@
 #!/usr/bin/env bash
 # ftm-blackboard-enforcer.sh
-# Stop hook that checks if meaningful work was done but no blackboard
-# experience was recorded. If so, blocks the stop and tells Claude
-# to write the experience first.
+# Stop hook that nudges Claude to record an experience if meaningful work
+# was done but no blackboard entry was written.
 #
-# "Meaningful work" = 3+ tool uses detected by the edit counter,
+# Uses additionalContext (not "decision: block") so Claude can still act on
+# the reminder. A blocking stop creates a deadlock — Claude can't write files
+# after the user ends the conversation.
+#
+# "Meaningful work" = 3+ edits tracked by the edit counter,
 # or ftm skills were invoked (checked via context.json).
 #
 # Hook: Stop
@@ -13,29 +16,23 @@ set -euo pipefail
 
 INPUT=$(cat)
 
-# Prevent infinite loop — if this hook already fired, let Claude stop
-STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
-if [[ "$STOP_HOOK_ACTIVE" == "true" ]]; then
-  exit 0
-fi
-
 STATE_DIR="$HOME/.claude/ftm-state"
 BB_DIR="$STATE_DIR/blackboard"
 EDIT_COUNTER="$STATE_DIR/.edit-count"
 CONTEXT_FILE="$BB_DIR/context.json"
 EXPERIENCES_DIR="$BB_DIR/experiences"
-EXPERIENCE_INDEX="$EXPERIENCES_DIR/index.json"
-
-CURRENT_SESSION="${CLAUDE_SESSION_ID:-unknown}"
 
 # Check 1: Were there meaningful edits this session?
+# Edit counter contains just a number now (no session ID).
+# If the counter file is recent (< 4 hours) and >= 3, count as meaningful.
 HAD_EDITS=false
 if [[ -f "$EDIT_COUNTER" ]]; then
-  STORED=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0:unknown")
-  STORED_SESSION=$(echo "$STORED" | cut -d: -f2)
-  STORED_COUNT=$(echo "$STORED" | cut -d: -f1)
-  if [[ "$STORED_SESSION" == "$CURRENT_SESSION" && "$STORED_COUNT" -ge 3 ]]; then
-    HAD_EDITS=true
+  COUNTER_AGE=$(( $(date +%s) - $(stat -c %Y "$EDIT_COUNTER" 2>/dev/null || stat -f %m "$EDIT_COUNTER" 2>/dev/null || echo "0") ))
+  if [[ "$COUNTER_AGE" -lt 14400 ]]; then
+    STORED_COUNT=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0")
+    if [[ "$STORED_COUNT" -ge 3 ]]; then
+      HAD_EDITS=true
+    fi
   fi
 fi
 
@@ -48,8 +45,10 @@ if [[ -f "$CONTEXT_FILE" ]]; then
   fi
 fi
 
-# If no meaningful work detected, allow stop
+# If no meaningful work detected, allow stop quietly
 if [[ "$HAD_EDITS" == "false" && "$HAD_SKILLS" == "false" ]]; then
+  # Clean up session markers
+  rm -f "$EDIT_COUNTER" "$STATE_DIR/.plan-presented" 2>/dev/null
   exit 0
 fi
 
@@ -58,19 +57,17 @@ TODAY=$(date +%Y-%m-%d)
 HAS_EXPERIENCE=false
 
 if [[ -d "$EXPERIENCES_DIR" ]]; then
-  # Check for experience files created today
   TODAY_EXPERIENCE=$(find "$EXPERIENCES_DIR" -name "${TODAY}*" -type f 2>/dev/null | head -1)
   if [[ -n "$TODAY_EXPERIENCE" ]]; then
     HAS_EXPERIENCE=true
   fi
 fi
 
-# Also check if context.json was updated this session (recent_decisions not empty)
+# Also check if context.json was updated today (recent_decisions not empty)
 if [[ -f "$CONTEXT_FILE" ]]; then
   DECISIONS_COUNT=$(jq -r '.recent_decisions | length' "$CONTEXT_FILE" 2>/dev/null || echo "0")
   LAST_UPDATED=$(jq -r '.session_metadata.last_updated // ""' "$CONTEXT_FILE" 2>/dev/null || echo "")
   if [[ "$DECISIONS_COUNT" -gt 0 && -n "$LAST_UPDATED" ]]; then
-    # Check if last_updated is from today
     if [[ "$LAST_UPDATED" == *"$TODAY"* ]]; then
       HAS_EXPERIENCE=true
     fi
@@ -78,17 +75,21 @@ if [[ -f "$CONTEXT_FILE" ]]; then
 fi
 
 if [[ "$HAS_EXPERIENCE" == "true" ]]; then
-  # Blackboard was written, allow stop
-  # Clean up session markers
+  # Blackboard was written, clean up and allow stop
   rm -f "$EDIT_COUNTER" "$STATE_DIR/.plan-presented" 2>/dev/null
   exit 0
 fi
 
-# Work was done but no blackboard write — block the stop
+# Work was done but no blackboard write — nudge (don't block)
 cat <<'JSON'
 {
-  "decision": "block",
-  "reason": "[ftm-blackboard-enforcer] You did meaningful work this session (3+ edits or ftm skills used) but did not record an experience to the blackboard. Before stopping, you MUST: (1) Update ~/.claude/ftm-state/blackboard/context.json with current_task status and recent_decisions. (2) Write an experience file to ~/.claude/ftm-state/blackboard/experiences/ with task_type, tags, outcome, lessons, files_touched, stakeholders, and decisions_made. (3) Update ~/.claude/ftm-state/blackboard/experiences/index.json with the new entry. This is how ftm learns — skipping it means the next session starts from zero."
+  "hookSpecificOutput": {
+    "hookEventName": "Stop",
+    "additionalContext": "[ftm-blackboard-enforcer] You did meaningful work this session but did not record an experience to the blackboard. Before finishing, please: (1) Update ~/.claude/ftm-state/blackboard/context.json with current_task status and recent_decisions. (2) Write an experience file to ~/.claude/ftm-state/blackboard/experiences/ with task_type, tags, outcome, and lessons. (3) Update ~/.claude/ftm-state/blackboard/experiences/index.json with the new entry. This is how ftm learns — skipping it means the next session starts from zero."
+  }
 }
 JSON
+
+# Clean up session markers regardless — don't let stale state carry over
+rm -f "$EDIT_COUNTER" "$STATE_DIR/.plan-presented" 2>/dev/null
 exit 0

package/hooks/ftm-plan-gate.sh

@@ -2,14 +2,13 @@
 # ftm-plan-gate.sh
 # PreToolUse hook for Edit/Write tools.
 #
-# Checks if a plan has been presented and approved for this session before
-# allowing code edits. If no plan marker exists and the session involves
-# a medium+ task (detected by ftm-state), injects additionalContext
+# Checks if a plan has been presented this session before allowing code edits.
+# If no plan marker exists and the edit count is climbing, injects warnings
 # telling Claude to stop and present a plan first.
 #
-# The marker file is created by Claude when it presents a plan — we check
-# for it here. If the marker doesn't exist but edits are happening, it
-# means Claude skipped the planning step.
+# The marker file (~/.claude/ftm-state/.plan-presented) is created by Claude
+# when it presents a plan. Any non-empty content counts as "plan presented".
+# The file is cleaned up by the blackboard enforcer at session end.
 #
 # Hook: PreToolUse (matcher: Edit|Write)
 
@@ -25,9 +24,7 @@ fi
 
 STATE_DIR="$HOME/.claude/ftm-state"
 PLAN_MARKER="$STATE_DIR/.plan-presented"
-SESSION_MARKER="$STATE_DIR/.session-id"
 EDIT_COUNTER="$STATE_DIR/.edit-count"
-SKILL_FILES_DIR="$HOME/.claude/skills"
 
 # Get the file being edited
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
@@ -47,37 +44,36 @@ if [[ "$FILE_PATH" == *".claude/skills/"* ]] || \
   exit 0
 fi
 
-# If plan marker exists and matches current session, allow
-CURRENT_SESSION="${CLAUDE_SESSION_ID:-unknown}"
-if [[ -f "$PLAN_MARKER" ]]; then
-  MARKER_SESSION=$(cat "$PLAN_MARKER" 2>/dev/null || echo "")
-  if [[ "$MARKER_SESSION" == "$CURRENT_SESSION" ]]; then
-    exit 0  # Plan was presented this session, allow edits
+# If plan marker exists (any content), allow edits
+if [[ -f "$PLAN_MARKER" ]] && [[ -s "$PLAN_MARKER" ]]; then
+  exit 0
+fi
+
+# Reset edit counter if it's stale (older than 4 hours = likely a new session)
+if [[ -f "$EDIT_COUNTER" ]]; then
+  COUNTER_AGE=$(( $(date +%s) - $(stat -c %Y "$EDIT_COUNTER" 2>/dev/null || echo "0") ))
+  if [[ "$COUNTER_AGE" -gt 14400 ]]; then
+    rm -f "$EDIT_COUNTER"
   fi
 fi
 
-# Count edits this session (without a plan marker)
+# Count edits without a plan marker
 EDIT_COUNT=0
 if [[ -f "$EDIT_COUNTER" ]]; then
-  STORED=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0:unknown")
-  STORED_SESSION=$(echo "$STORED" | cut -d: -f2)
-  if [[ "$STORED_SESSION" == "$CURRENT_SESSION" ]]; then
-    EDIT_COUNT=$(echo "$STORED" | cut -d: -f1)
-  fi
+  EDIT_COUNT=$(cat "$EDIT_COUNTER" 2>/dev/null || echo "0")
 fi
 
 EDIT_COUNT=$((EDIT_COUNT + 1))
-echo "${EDIT_COUNT}:${CURRENT_SESSION}" > "$EDIT_COUNTER"
+echo "$EDIT_COUNT" > "$EDIT_COUNTER"
 
-# First 2 edits get a warning injected as context (don't block — could be micro tasks)
+# First 2 edits get a soft reminder (don't block — could be micro tasks)
 # After 3+ edits without a plan marker, escalate the warning
 if [[ $EDIT_COUNT -le 2 ]]; then
-  # Soft reminder — inject context but allow
   cat <<'JSON'
 {
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
-    "additionalContext": "[ftm-plan-gate] You are editing files without having presented a plan this session. If this task is medium+ (touches 3+ files, involves external systems, or has stakeholder coordination), you MUST present a numbered plan and get user approval BEFORE editing code. If this is a micro/small task, you can proceed — but create the plan marker by writing the current session ID to ~/.claude/ftm-state/.plan-presented after confirming the task is genuinely small. To create the marker: Write tool → ~/.claude/ftm-state/.plan-presented with content being the session ID."
+    "additionalContext": "[ftm-plan-gate] You are editing files without having presented a plan this session. If this task is medium+ (touches 3+ files, involves external systems, or has stakeholder coordination), you MUST present a numbered plan and get user approval BEFORE editing code. If this is a micro/small task, you can proceed — but create the plan marker: write any content to ~/.claude/ftm-state/.plan-presented to acknowledge you've considered it."
   }
 }
 JSON
@@ -89,7 +85,7 @@ cat <<'JSON'
 {
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
-    "additionalContext": "[ftm-plan-gate WARNING] You have made 3+ file edits this session without presenting a plan. This is exactly the 'grinding without a plan' pattern that ftm-mind is supposed to prevent. STOP editing and do one of: (1) Present a numbered plan to the user and wait for approval, then write the session ID to ~/.claude/ftm-state/.plan-presented. (2) If the user explicitly said 'just do it' or this is genuinely a micro task, write the plan marker to acknowledge you've considered it. Do NOT continue editing without addressing this."
+    "additionalContext": "[ftm-plan-gate WARNING] You have made 3+ file edits this session without presenting a plan. This is exactly the 'grinding without a plan' pattern that ftm-mind is supposed to prevent. STOP editing and do one of: (1) Present a numbered plan to the user and wait for approval, then write any content to ~/.claude/ftm-state/.plan-presented. (2) If the user explicitly said 'just do it' or this is genuinely a micro task, write the plan marker to acknowledge you've considered it. Do NOT continue editing without addressing this."
   }
 }
 JSON