fix: address review — guard grooming in gardener-poll.sh, doc fixes

- Add --recipes-only flag to gardener-poll.sh to skip grooming call when
  invoked by the formula's ci-escalation-recipes step (prevents double-run)
- Update formula step to pass --recipes-only
- Add lib/file-action-issue.sh to AGENTS.md shared helpers table
- Clarify TOML arg scope in gardener trigger description
- Fix log prefixes in gardener-run.sh (poll: → run:)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gardener/gardener-poll.sh

@@ -25,8 +25,16 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 FACTORY_ROOT="$(dirname "$SCRIPT_DIR")"
 
+# --recipes-only: skip grooming (used by formula ci-escalation-recipes step
+# to avoid double-running grooming which the formula handles as its own step)
+RECIPES_ONLY=0
+if [ "${1:-}" = "--recipes-only" ]; then
+  RECIPES_ONLY=1
+  shift
+fi
+
 # Load shared environment (with optional project TOML override)
-# Usage: gardener-poll.sh [projects/harb.toml]
+# Usage: gardener-poll.sh [--recipes-only] [projects/harb.toml]
 export PROJECT_TOML="${1:-}"
 # shellcheck source=../lib/env.sh
 source "$FACTORY_ROOT/lib/env.sh"
@@ -108,8 +116,13 @@ Instructions:
 done
 
 # ── Backlog grooming (delegated to gardener-agent.sh) ────────────────────
-log "Invoking gardener-agent.sh for backlog grooming"
-bash "$SCRIPT_DIR/gardener-agent.sh" "${1:-}" || log "WARNING: gardener-agent.sh exited with error"
+# Skipped with --recipes-only (formula's grooming step handles this)
+if [ "$RECIPES_ONLY" -eq 0 ]; then
+  log "Invoking gardener-agent.sh for backlog grooming"
+  bash "$SCRIPT_DIR/gardener-agent.sh" "${1:-}" || log "WARNING: gardener-agent.sh exited with error"
+else
+  log "Skipping grooming (--recipes-only mode)"
+fi
 
 
 # ── Recipe matching engine ────────────────────────────────────────────────

gardener/gardener-run.sh

@@ -27,7 +27,7 @@ log() { echo "[$(date -u +%Y-%m-%dT%H:%M:%S)Z] $*" >> "$LOG_FILE"; }
 if [ -f "$LOCK_FILE" ]; then
   LOCK_PID=$(cat "$LOCK_FILE" 2>/dev/null || true)
   if [ -n "$LOCK_PID" ] && kill -0 "$LOCK_PID" 2>/dev/null; then
-    log "poll: gardener-run running (PID $LOCK_PID)"
+    log "run: gardener-run running (PID $LOCK_PID)"
     exit 0
   fi
   rm -f "$LOCK_FILE"
@@ -38,7 +38,7 @@ trap 'rm -f "$LOCK_FILE"' EXIT
 # ── Memory guard ──────────────────────────────────────────────────────────
 AVAIL_MB=$(free -m | awk '/Mem:/{print $7}')
 if [ "${AVAIL_MB:-0}" -lt 2000 ]; then
-  log "poll: skipping — only ${AVAIL_MB}MB available (need 2000)"
+  log "run: skipping — only ${AVAIL_MB}MB available (need 2000)"
   exit 0
 fi
 
@@ -60,7 +60,7 @@ _rc=0
 file_action_issue "run-gardener" "action: run-gardener — periodic housekeeping" "$ISSUE_BODY" || _rc=$?
 case "$_rc" in
   0) ;;
-  1) log "poll: open run-gardener action issue already exists — skipping"
+  1) log "run: open run-gardener action issue already exists — skipping"
      log "--- Gardener run done ---"
      exit 0 ;;
   2) log "ERROR: 'action' label not found — cannot file gardener issue"