feed-the-machine 1.2.0 → 1.3.1

package/ftm-retro/SKILL.md

@@ -51,19 +51,73 @@ Never ask the user to provide data you can find yourself. Read the files.
 
 ---
 
-## Scoring Flow
+## Scoring Dimensions
 
-Score execution across 5 dimensions. Read `references/protocols/SCORING-RUBRICS.md` for the full rubric for each dimension (scale breakpoints, evidence requirements, formula for Dimension 4).
+Score each dimension 0–10 with a citation to specific data. Do not estimate without evidence — if data is missing, note it and score conservatively.
 
-**The 5 dimensions:**
+### 1. Wave Parallelism Efficiency (0–10)
 
-1. **Wave Parallelism Efficiency** — were independent tasks actually dispatched in parallel?
-2. **Audit Pass Rate** — what percentage of tasks passed ftm-audit on the first attempt?
-3. **Codex Gate Pass Rate** — what percentage of waves passed the ftm-codex-gate on the first attempt?
-4. **Retry and Fix Count** — how many total review-fix cycles were needed? Lower is better.
-5. **Execution Smoothness** — evidence-grounded assessment of blockers, ambiguities, and manual interventions.
+Were independent tasks actually dispatched in parallel? Could more tasks have been parallelized?
 
-Every score requires a citation to specific data. If data for a dimension is unavailable, note the gap and score conservatively.
+- **10**: Every task that could run in parallel did. No serial bottlenecks where parallelism was possible.
+- **7–9**: Minor serial steps that could have been parallel (e.g., final post-processing tasks run sequentially).
+- **4–6**: Significant parallelism opportunities missed. Tasks that had no dependencies ran serially.
+- **1–3**: Nearly all tasks ran serially despite having no dependencies on each other.
+- **0**: Everything was serial regardless of dependency structure.
+
+Evidence to cite: wave structure from PROGRESS.md, task dependency graph, agent dispatch timestamps.
+
+### 2. Audit Pass Rate (0–10)
+
+What percentage of tasks passed ftm-audit on the first attempt?
+
+- **10**: 100% first-pass. No task needed a fix cycle.
+- **8**: 90%+ first-pass. One or two tasks needed minor fixes.
+- **6**: 75–89% first-pass.
+- **4**: 50–74% first-pass. Roughly half the tasks needed audit remediation.
+- **2**: Below 50% first-pass.
+- **0**: Every single task failed audit on the first attempt.
+
+Evidence to cite: per-task audit results (pass/fail counts, auto-fix counts, manual-fix counts).
+
+### 3. Codex Gate Pass Rate (0–10)
+
+What percentage of waves passed the ftm-codex-gate on the first attempt?
+
+- **10**: All waves passed on first gate run.
+- **7–9**: One wave needed a fix-and-retry.
+- **4–6**: Multiple waves needed retries.
+- **1–3**: Most waves failed the gate at least once.
+- **0**: Every wave failed the gate.
+
+Evidence to cite: codex gate results per wave (pass/fail, failure types).
+
+### 4. Retry and Fix Count (0–10)
+
+How many total review-fix cycles were needed across all tasks and waves? Lower is better.
+
+Formula: score = max(0, 10 - (total_retries / task_count) * 5)
+
+- **10**: Zero retries.
+- **8**: Fewer than 0.5 retries per task on average.
+- **6**: 0.5–1.0 retries per task.
+- **4**: 1–2 retries per task.
+- **2**: 2–3 retries per task.
+- **0**: More than 3 retries per task on average.
+
+Evidence to cite: total retries, broken down by type (audit fix, codex gate retry, manual intervention).
+
+### 5. Execution Smoothness (0–10)
+
+Subjective but evidence-grounded assessment. Were there blockers, ambiguous plan steps, confusing errors, or required manual interventions?
+
+- **10**: Fully autonomous from start to finish. No blockers, no ambiguity, no manual steps.
+- **7–9**: Minor friction — one clarification needed, one unexpected error handled gracefully.
+- **4–6**: Moderate friction — multiple ambiguities, one blocker that paused execution, one manual intervention.
+- **1–3**: Significant friction — repeated blockers, unclear plan steps that caused wrong-direction work, multiple manual interventions.
+- **0**: Execution could not proceed without constant human steering.
+
+Evidence to cite: error log entries, any manual interventions recorded in PROGRESS.md, plan ambiguities encountered.
 
 ---
 
@@ -75,28 +129,122 @@ Every score requires a citation to specific data. If data for a dimension is una
 mkdir -p ~/.claude/ftm-retros/
 ```
 
-### Step 2: Check for past retros
+### Step 2: Generate plan slug
 
-Before writing anything, check whether any `.md` files exist in `~/.claude/ftm-retros/`. If they do, read them all. You will use them for the Pattern Analysis section.
+Take the plan title, lowercase it, replace spaces with hyphens, strip all non-alphanumeric characters except hyphens.
 
-### Step 3: Write the report
+Examples:
+- "FTM Ecosystem Expansion" → `ftm-ecosystem-expansion`
+- "Fix Auth Bug + Rate Limiting" → `fix-auth-bug-rate-limiting`
+- "v2.0 API Refactor" → `v20-api-refactor`
+
+### Step 3: Check for past retros
+
+Before writing anything, check whether any `.md` files exist in `~/.claude/ftm-retros/`. If they do, read them all. You will use them for the Pattern Analysis section.
 
-Read `references/templates/REPORT-FORMAT.md` for the exact output template, slug generation rules, and section format.
+### Step 4: Write the report
 
 Save to: `~/.claude/ftm-retros/{plan-slug}-{YYYY-MM-DD}.md`
 
+Use this exact format:
+
+```markdown
+# Retro: {Plan Title}
+
+**Date:** {YYYY-MM-DD}
+**Plan:** {absolute path to plan file}
+**Duration:** {total execution time, e.g. "47 minutes"}
+
+## Scores
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Wave Parallelism | X/10 | {1-sentence justification with data} |
+| Audit Pass Rate | X/10 | {N}/{total} tasks first-pass |
+| Codex Gate Pass Rate | X/10 | {N}/{total} waves first-pass |
+| Retry/Fix Count | X/10 | {total retries} across {N} tasks |
+| Execution Smoothness | X/10 | {1-sentence justification} |
+
+**Overall: {sum}/50**
+
+## Raw Data
+
+- Tasks: {N}
+- Waves: {N}
+- Agents spawned: {N}
+- Audit findings: {N} total ({N} auto-fixed, {N} manual)
+- Codex gate results: Wave 1: pass | Wave 2: fail → pass | Wave 3: pass
+- Errors/blockers: {list any, or "none"}
+
+## What Went Well
+
+{2–4 specific observations, each grounded in a data point or task number.}
+
+Example format:
+- **Task 3 (auth middleware)** completed in a single commit with zero audit findings. The agent prompt had clear acceptance criteria and a scoped file list — the agent never wandered.
+- **Wave 2 parallelism** was fully utilized: all 4 tasks dispatched simultaneously, cutting estimated serial time from ~32 minutes to ~9 minutes.
+
+## What Was Slow
+
+{2–4 specific bottlenecks with timing data or retry counts where available.}
+
+Example format:
+- **ftm-audit Phase 1 (knip)** repeated full project analysis for each task in wave 3, even though tasks only touched 2–3 files each. Added ~40s × 5 tasks = ~3.5 minutes of unnecessary scanning.
+- **Task 7 needed 3 audit fix cycles** due to an import path that kept regenerating incorrectly. The agent prompt did not specify the alias configuration in tsconfig.paths.
+
+## Proposed Improvements
+
+{3–5 specific, actionable suggestions. Each must identify: which skill to change, what to change exactly, and why it would help.}
+
+Format each as:
+**N. {Short title}** — {Skill to change} — {Specific change} — {Expected impact}
+
+Examples:
+1. **Cache knip results within a wave** — ftm-audit — In Phase 1, check whether knip results are already cached for the current wave (via a temp file at `/tmp/ftm-knip-cache-{wave-id}.json`). Only re-run knip if the cache is missing or if the files changed by this task differ from cached scope. Expected: 3× speedup for ftm-audit on large projects with many tasks per wave.
+2. **Dispatch Instrumentor and Researcher in parallel** — ftm-debug — These two agents have no shared state and currently run sequentially. Dispatch them simultaneously. Expected: ~40% reduction in ftm-debug total runtime.
+3. **Add tsconfig.paths to agent context for TypeScript projects** — ftm-executor — When generating agent prompts for TypeScript tasks, include the relevant `paths` aliases from `tsconfig.json`. Expected: eliminates the import-alias regeneration loop that caused 3 retries on Task 7.
+
+## Pattern Analysis
+
+{Only include this section if past retros exist in ~/.claude/ftm-retros/}
+
+### Recurring Issues
+
+{List problems that appeared in 2 or more retros. Format: "Issue description — appeared in: retro-slug-1, retro-slug-2"}
+
+### Score Trends
+
+{Compare overall scores across retros. Are they improving, declining, or stable? Cite actual numbers.}
+
+Example: Overall scores: 32/50 → 38/50 → 41/50 across the last 3 retros. Parallelism and smoothness improving; audit pass rate stuck at 6/10 for all three runs.
+
+### Unaddressed Suggestions
+
+{List proposed improvements from past retros that have not yet been implemented. These get escalated — flag them explicitly.}
+
+Format: "**[ESCALATED]** {suggestion} — first proposed in {retro-slug-date}, appeared {N} times"
+```
+
 ---
 
 ## Key Behaviors
 
+### Evidence-first scoring
+
+Every score needs a citation. "Tasks passed audit" is not a citation. "12/14 tasks passed audit on first attempt; Tasks 3 and 9 each needed one auto-fix cycle" is a citation. If the data to score a dimension is genuinely unavailable, note the gap explicitly and score conservatively (assume worst case for that dimension).
+
 ### Improvement specificity
 
-"Improve parallelism" is not an improvement proposal. "Add a dependency pre-check step to ftm-executor Phase 2 that flags tasks with no declared dependencies as parallelizable, and warn when they are dispatched serially" is an improvement proposal. Every proposed improvement must be concrete enough that a future session could implement it from the description alone.
+"Improve parallelism" is not an improvement proposal. "Add a dependency pre-check step to ftm-executor Phase 2 that flags tasks with no declared dependencies as parallelizable, and warn when they are dispatched serially" is an improvement proposal. Every proposed improvement must be concrete enough that a future session could implement it from the description alone without asking clarifying questions.
 
 ### Pattern escalation
 
 Recurring issues that have appeared in 3+ retros without being addressed should be flagged with `[ESCALATED - 3+ occurrences]` and moved to the top of the Proposed Improvements list. These are systemic problems, not one-off noise.
 
+### No vibes
+
+Do not write "the execution felt smooth" or "agents seemed efficient." Write "0 manual interventions were required and all errors were caught and auto-resolved by ftm-audit Phase 2." The report is read by future executions that need to calibrate behavior, not by humans looking for encouragement.
+
 ---
 
 ## Output
@@ -111,7 +259,7 @@ Top issue: {single most impactful bottleneck in one sentence}
 Top suggestion: {single highest-value proposed improvement in one sentence}
 ```
 
-Do not print the full report to the terminal — it lives in the file.
+Do not print the full report to the terminal — it lives in the file. The summary above is sufficient for the user to know the run completed and where to find details.
 
 ---
 
@@ -137,7 +285,7 @@ Confidence: [low/medium/high]"
 
 ### Experience Entry Creation
 
-Write a structured experience entry to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`.
+Write a structured experience entry to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json` following the schema in blackboard-schema.md.
 
 Key fields:
 - `task_type`: derived from the task
@@ -177,17 +325,6 @@ During the first ~10 interactions (when `experiences/index.json` has `total_coun
 - Set `confidence: "low"` on all entries
 - Prioritize breadth of recording over depth of analysis
 
-## Blackboard Write
-
-After completing, update:
-1. `~/.claude/ftm-state/blackboard/context.json`:
-   - Set current_task status to "complete"
-   - Append decision summary to recent_decisions (cap at 10)
-   - Update session_metadata.skills_invoked and last_updated
-2. Write experience file to `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
-3. Update `experiences/index.json` with the new entry
-4. Emit `task_completed`
-
 ## Requirements
 
 - reference: `PROGRESS.md` | optional | executor progress log for auto-triggered mode

package/ftm-upgrade/SKILL.md

@@ -13,7 +13,7 @@ description: Self-upgrade mechanism for ftm skills ecosystem. Checks GitHub Rele
 
 # ftm-upgrade
 
-Self-upgrade mechanism for the ftm skills ecosystem. Fetches the latest release from `kkudumu/ftm-brain` on GitHub, compares it to the locally installed version, and copies updated skill files in place.
+Self-upgrade mechanism for the ftm skills ecosystem. Fetches the latest release from `kkudumu/ftm-skills` on GitHub, compares it to the locally installed version, and copies updated skill files in place.
 
 ---
 
@@ -135,7 +135,7 @@ Map `CHECK_FAILED <reason>` codes to user-facing messages:
 |---|---|
 | `gh_not_installed` | GitHub CLI is not installed. Install it with: `brew install gh` (macOS) or see https://cli.github.com |
 | `no_internet` | Cannot reach GitHub. Check your internet connection and try again. |
-| `repo_not_found` | Repository `kkudumu/ftm-brain` not found. Verify you have access to the repository. |
+| `repo_not_found` | Repository `kkudumu/ftm-skills` not found. Verify you have access to the repository. |
 | `no_releases_found` | No releases found in the repository yet. Check back later. |
 | any other reason | Version check failed: `<reason>`. Try running manually: `bash ~/.claude/skills/ftm-upgrade/scripts/check-version.sh` |
 
@@ -148,9 +148,9 @@ Map `CHECK_FAILED <reason>` codes to user-facing messages:
 | `~/.claude/skills/ftm-upgrade/scripts/check-version.sh` | Query GitHub for latest release, cache result 60 min |
 | `~/.claude/skills/ftm-upgrade/scripts/upgrade.sh` | Download and install latest release |
 
-**Cache location**: `~/.cache/ftm-brain/version-check`
+**Cache location**: `~/.cache/ftm-skills/version-check`
 **Version file**: `~/.claude/skills/ftm-version.txt`
-**Repo**: `kkudumu/ftm-brain`
+**Repo**: `kkudumu/ftm-skills`
 
 ## Requirements
 

package/hooks/ftm-blackboard-enforcer.sh

@@ -1,41 +1,39 @@
 #!/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
 
 set -euo pipefail
 
+# shellcheck disable=SC2034
 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 +46,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 +58,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 +76,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