@groundnuty/macf 0.2.34 → 0.2.36

package/scripts/check-close-keyword.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+#
+# check-close-keyword.sh — Claude Code PreToolUse hook that blocks
+# `gh pr create` / `gh pr edit` invocations whose body / title contains a
+# GitHub auto-close keyword (`close`/`closes`/`closed`/`fix`/`fixes`/`fixed`/
+# `resolve`/`resolves`/`resolved`) adjacent to an issue ref (`#N` or
+# `owner/repo#N`) **filed by another agent**. On merge, such a keyword
+# auto-closes the referenced issue — bypassing reporter-owns-closure
+# (coordination.md §Issue Lifecycle 1). The keyword parser is negation-blind
+# and context-blind (tables, checklists, quotes, code fences don't shield it),
+# so cognitive discipline has proven insufficient (4 self-inflicted recurrences
+# — macf#316/#410/#430). This is the Path-2 structural backstop.
+#
+# Hook contract: JSON on stdin, exit 0 = allow, exit 2 = block (stderr is fed
+# back to Claude as the error). Mirrors check-gh-token.sh / check-mention-
+# routing.sh in shape (wrapper-aware invocation matching, fail-open on parse
+# error so a broken hook never bricks the harness).
+#
+# Discriminator: blocks ONLY when the referenced issue's author is NOT the
+# acting bot. A self-filed `Closes #own` is legitimate and passes. The acting
+# bot login is `${MACF_AGENT_NAME}[bot]` (falls back to $GIT_AUTHOR_NAME, which
+# env.identity sets to `<agent_name>[bot]`).
+#
+# Override: MACF_SKIP_CLOSE_CHECK=1 bypasses (deliberate cross-fix, or the rare
+# case the heuristic mis-resolves authorship).
+#
+# Refs: groundnuty/macf#431 (this hook); coordination.md §Issue Lifecycle 1
+#       (the 9 forbidden variants + reporter-owns-closure); silent-fallback-
+#       hazards.md Instance 2; #140 / #244+#272 / #270 (sister Path-2 hooks).
+set -euo pipefail
+
+# Cheap exit on operator override — no stdin read, no parsing.
+if [[ "${MACF_SKIP_CLOSE_CHECK:-}" == "1" ]]; then
+  exit 0
+fi
+
+# Read PreToolUse payload. Fall through to allow on parse error — a broken
+# hook must not brick the harness. Same defense-in-depth as the sister hooks.
+INPUT_JSON="$(cat)"
+COMMAND="$(jq -r '.tool_input.command // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+[[ -z "$COMMAND" ]] && exit 0
+
+# Wrapper-aware match for `gh pr create` / `gh pr edit`. Mirrors check-gh-
+# token.sh / check-mention-routing.sh — covers sudo, env VAR=, watch, ionice,
+# setsid, nice, time prefix wrappers + chained-form leadins `;` `|` `&` `(`
+# (subshell) + bare `VAR=val gh ...`. These are the two subcommands whose
+# body/title lands in the merge commit (and thus can auto-close on merge).
+GH_PR_PATTERN='(^|[[:space:];|&(])(sudo[[:space:]]+|env[[:space:]]+([A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*|watch[[:space:]]+|ionice[[:space:]]+|setsid[[:space:]]+|nice[[:space:]]+|time[[:space:]]+|[A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*gh[[:space:]]+pr[[:space:]]+(create|edit)([[:space:]]|$)'
+
+# Shell-wrapper bypass: `bash -c "gh pr create ..."` and variants.
+SHELL_C_GH_PR_PATTERN='(^|[[:space:];|&(])(sudo[[:space:]]+|env[[:space:]]+([A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*|[A-Za-z_][A-Za-z_0-9]*=[^[:space:]]*[[:space:]]+)*(bash|sh|zsh)[[:space:]]+(-[a-zA-Z]+[[:space:]]+)*-[a-zA-Z]*c[[:space:]]+[^[:space:]].*gh[[:space:]]+pr[[:space:]]+(create|edit)([[:space:]]|$)'
+
+if [[ ! "$COMMAND" =~ $GH_PR_PATTERN ]] && [[ ! "$COMMAND" =~ $SHELL_C_GH_PR_PATTERN ]]; then
+  exit 0
+fi
+
+# ── Acting bot login ─────────────────────────────────────────────────────
+# Prefer MACF_AGENT_NAME (env.identity exports it as the agent stem, e.g.
+# `macf-code-agent`); the bot login is `<stem>[bot]`. Fall back to
+# GIT_AUTHOR_NAME (env.identity sets it to `<stem>[bot]` already). May be empty
+# in a workspace with no identity env — handled conservatively below.
+ACTING_BOT=""
+if [[ -n "${MACF_AGENT_NAME:-}" ]]; then
+  # Strip a trailing `[bot]` first so a misconfigured MACF_AGENT_NAME that
+  # already carries it doesn't become `<name>[bot][bot]` (which would
+  # mis-block self-filed closes). Append exactly once.
+  ACTING_BOT="${MACF_AGENT_NAME%"[bot]"}[bot]"
+elif [[ -n "${GIT_AUTHOR_NAME:-}" && "${GIT_AUTHOR_NAME}" == *"[bot]" ]]; then
+  ACTING_BOT="${GIT_AUTHOR_NAME}"
+fi
+
+# ── Repo the PR targets (for refs without an owner/repo prefix) ──────────
+# Parse `--repo owner/repo` (or `--repo=owner/repo`) from the command; fall
+# back to gh's default repo resolution for the cwd.
+PR_REPO="$(grep -oE -- '--repo[ =][^[:space:]]+' <<<"$COMMAND" | head -1 | sed -E 's/^--repo[ =]//' | tr -d "\"'" || true)"
+if [[ -z "$PR_REPO" ]]; then
+  PR_REPO="$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null || true)"
+fi
+
+# ── Build the scan text: the raw command (covers inline --body, --title, and
+#    heredoc text) plus the contents of any --body-file (a file path, NOT an
+#    inline arg — the bypass most likely to slip a body-only scan). ─────────
+# `-F` is gh's documented short alias for `--body-file` (`gh pr create --help`:
+# `-F, --body-file file`), so normalize the space/`=` forms `-F path` / `-F=path`
+# → `--body-file …` before extraction, else a peer close-keyword in a `-F`-passed
+# file slips the scan (groundnuty/macf#431 review must-fix 1).
+#
+# Known inherent non-guards (backstop, not airtight): `--body-file -` / `-F -`
+# (stdin — unreadable at hook-fire time); the glued short form `-Fpath`; and a
+# path-prefixed binary (`/usr/bin/gh pr create …`, where the leading boundary
+# class doesn't see a bare `gh`). The authorship+merge-time reality still
+# catches the common forms; these are documented so they're known, not silent.
+NORM_CMD="$(sed -E 's/(^|[[:space:]])-F([ =])/\1--body-file\2/g' <<<"$COMMAND")"
+SCAN_TEXT="$COMMAND"
+while IFS= read -r bf; do
+  [[ -z "$bf" ]] && continue
+  bf="${bf%\"}"; bf="${bf#\"}"; bf="${bf%\'}"; bf="${bf#\'}"
+  if [[ -f "$bf" ]]; then
+    SCAN_TEXT+=$'\n'"$(cat "$bf" 2>/dev/null || true)"
+  fi
+done < <(grep -oE -- '--body-file[ =][^[:space:]]+' <<<"$NORM_CMD" | sed -E 's/^--body-file[ =]//' || true)
+
+# ── Find close-keyword → issue-ref adjacencies ───────────────────────────
+# Mirrors GitHub's actual parser: the keyword must be a whole word
+# (word-boundary before it) and immediately followed by only whitespace then
+# the ref — `fix the bug in #1` does NOT auto-close, so it must NOT match.
+# The ref may carry an optional `owner/repo` prefix (cross-repo close, e.g.
+# `closes groundnuty/macf#418` in a devops-toolkit PR — lands in the squash
+# commit + closes the referenced repo's issue).
+KW_ALT='close|closes|closed|fix|fixes|fixed|resolve|resolves|resolved'
+# After the keyword, either a `:` + optional space (`Closes: #5` AND `Closes:#5`)
+# OR required whitespace (`Closes #5`) — but NOT `closes#5` (no separator, which
+# GitHub does not auto-close). The leading boundary `[^A-Za-z]` (or line start)
+# keeps `unfixes #1` / `prefixes #1` from matching.
+ADJ_RE="(^|[^A-Za-z])(${KW_ALT})(:[[:space:]]*|[[:space:]]+)([A-Za-z0-9._-]+/[A-Za-z0-9._-]+)?#[0-9]+"
+
+# grep -o yields each match including the optional leading boundary char;
+# strip it so each token is `<kw>[ ](<owner/repo>)?#N`.
+MATCHES="$(grep -oiE "$ADJ_RE" <<<"$SCAN_TEXT" | sed -E 's/^[^A-Za-z]+//' || true)"
+[[ -z "$MATCHES" ]] && exit 0
+
+# ── Resolve authorship for each unique ref + classify ────────────────────
+# Returns one of: NOTFOUND (no such issue → safe, no auto-close target),
+# OK:<PR|ISSUE>:<login>, or APIERROR:<msg>.
+resolve_issue() {
+  local repo="$1" num="$2" out rc err errfile
+  # Single gh call: capture stdout + stderr + rc atomically so the
+  # success/404/error classification can't split across two flaky calls.
+  errfile="$(mktemp)"
+  out="$(GH_PAGER= gh api "repos/${repo}/issues/${num}" 2>"$errfile")"; rc=$?
+  err="$(cat "$errfile" 2>/dev/null || true)"; rm -f "$errfile"
+  if [[ $rc -ne 0 ]]; then
+    if grep -qiE '404|not found' <<<"$err"; then
+      echo "NOTFOUND"
+    else
+      echo "APIERROR:$(tr '\n' ' ' <<<"$err" | cut -c1-120)"
+    fi
+    return 0
+  fi
+  local login ispr
+  login="$(jq -r '.user.login // ""' <<<"$out")"
+  ispr="$(jq -r 'if .pull_request then "PR" else "ISSUE" end' <<<"$out")"
+  echo "OK:${ispr}:${login}"
+}
+
+BLOCKED=""        # accumulated human-readable offenders
+SEEN=""           # dedup set of "repo#N"
+
+while IFS= read -r m; do
+  [[ -z "$m" ]] && continue
+  num="$(grep -oE '#[0-9]+' <<<"$m" | head -1 | tr -d '#')"
+  [[ -z "$num" ]] && continue
+  prefix="$(grep -oE '[A-Za-z0-9._-]+/[A-Za-z0-9._-]+#' <<<"$m" | head -1 | sed 's/#$//' || true)"
+  kw="$(grep -oiE "^(${KW_ALT})" <<<"$m")"
+  target_repo="${prefix:-$PR_REPO}"
+
+  # Can't determine which repo → can't verify authorship. Conservative block.
+  if [[ -z "$target_repo" ]]; then
+    BLOCKED+=$'\n'"  - \"${kw} #${num}\" → could not determine target repo (pass --repo or run from the repo)"
+    continue
+  fi
+
+  key="${target_repo}#${num}"
+  case " $SEEN " in *" $key "*) continue ;; esac
+  SEEN+=" $key"
+
+  res="$(resolve_issue "$target_repo" "$num")"
+  case "$res" in
+    NOTFOUND)
+      : # no such issue → nothing to auto-close → allow
+      ;;
+    OK:PR:*)
+      : # a PR, not an issue → auto-close keywords don't close PRs → allow
+      ;;
+    OK:ISSUE:*)
+      login="${res#OK:ISSUE:}"
+      if [[ -n "$ACTING_BOT" && "${login,,}" == "${ACTING_BOT,,}" ]]; then
+        : # self-filed → legitimate auto-close → allow
+      elif [[ -z "$ACTING_BOT" ]]; then
+        BLOCKED+=$'\n'"  - \"${kw} ${prefix:+${prefix}}#${num}\" → ${target_repo}#${num} filed by ${login}; could not confirm you are the author (no MACF_AGENT_NAME / GIT_AUTHOR_NAME)"
+      else
+        BLOCKED+=$'\n'"  - \"${kw} ${prefix:+${prefix}}#${num}\" → ${target_repo}#${num} filed by ${login} (not you, ${ACTING_BOT})"
+      fi
+      ;;
+    APIERROR:*)
+      BLOCKED+=$'\n'"  - \"${kw} ${prefix:+${prefix}}#${num}\" → could not verify ${target_repo}#${num} author (API: ${res#APIERROR:})"
+      ;;
+  esac
+done <<<"$MATCHES"
+
+[[ -z "$BLOCKED" ]] && exit 0
+
+cat >&2 <<ERR
+BLOCKED by MACF close-keyword guard: this \`gh pr create/edit\` would auto-close
+an issue you did not file when the PR merges, bypassing reporter-owns-closure
+(coordination.md §Issue Lifecycle 1).
+
+Offending close-keyword reference(s):${BLOCKED}
+
+GitHub's auto-close parser fires on \`<keyword> #N\` adjacency in a PR body or
+title — negation-blind and context-blind (tables, checklists, quotes, and code
+fences do NOT shield it). On merge it closes the referenced issue before the
+reporter can verify the fix matches their intent.
+
+Fix: replace the close-keyword with \`Refs\` (which references without closing):
+  Wrong:  closes #${num:-N}            Right:  Refs #${num:-N}
+  Wrong:  fixes owner/repo#${num:-N}   Right:  Refs owner/repo#${num:-N}
+
+Then the reporter closes it after verifying, per coordination.md.
+
+Override (ONLY for a deliberate cross-fix, or your OWN issue the check
+mis-resolved):
+  export MACF_SKIP_CLOSE_CHECK=1
+
+Refs: groundnuty/macf#431 (this hook); coordination.md §Issue Lifecycle 1
+(the 9 forbidden variants); silent-fallback-hazards.md Instance 2.
+ERR
+exit 2

package/scripts/emit-turn-receipt.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — turn-ack receipt for routed prompts
+# (groundnuty/macf#444 Option D, piece 2).
+#
+# When the router injects a prompt it appends a correlation marker
+# `[macf-route:<run_id>:<agent>]` (macf-actions#45, piece 1). When that prompt
+# is submitted AS A TURN, this hook fires and emits a `turn_processed` OTel
+# span carrying (routed_run_id, agent). A reconciler (piece 4) joins the
+# router's delivered-pairs log against these spans: a delivered route with no
+# matching span past the open-threshold = a dropped ping that surfaces
+# structurally (closes the #437 send≠receipt gap). A prompt with NO marker
+# (a typed prompt, a non-routed turn) is a no-op — exit 0, emit nothing.
+#
+# Registered `async: true` (settings.json) so it never adds turn latency. It
+# NEVER blocks the turn: any failure path exits 0 (with a stderr WARN on a
+# genuine emit error — fail-loud per silent-fallback-hazards.md Instance 8).
+#
+# Dependency: a live OTLP endpoint (OTEL_EXPORTER_OTLP_ENDPOINT — populated on
+# substrate by the #418 launcher OTEL block). Absent/unreachable → curl fails
+# → WARN, no span, no crash. So this ships safely before #418's relaunch; it
+# simply no-ops-with-WARN until substrate OTel is live.
+set -uo pipefail
+
+INPUT="$(cat)"
+
+# Extract the submitted prompt text. jq if available; else scan the raw payload.
+PROMPT=""
+if command -v jq >/dev/null 2>&1; then
+  PROMPT="$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)"
+fi
+[ -z "$PROMPT" ] && PROMPT="$INPUT"
+
+# Route-correlation markers: [macf-route:<digits>:<kebab-agent>]. No match → not
+# a routed prompt → no-op. A COALESCED turn (a busy agent processing several
+# queued routed pings in one turn) carries MULTIPLE markers — emit a receipt for
+# EACH distinct one. A receipt then means "the marked prompt reached the agent",
+# not "a distinct turn happened". (Was `head -1`, which under-emitted → the
+# macf#444 reconciler false-flagged the un-receipted markers as drops — #462.)
+MARKERS="$(printf '%s' "$PROMPT" | grep -oE '\[macf-route:[0-9]+:[a-z0-9-]+\]' | sort -u || true)"
+[ -z "$MARKERS" ] && exit 0
+
+# Need curl + openssl to emit; absent → degrade silently (no span, no noise).
+command -v curl >/dev/null 2>&1 || exit 0
+command -v openssl >/dev/null 2>&1 || exit 0
+
+BASE="${OTEL_EXPORTER_OTLP_ENDPOINT:-http://127.0.0.1:14318}"
+BASE="${BASE%/v1/traces}"
+
+# One independent span per distinct marker (own trace/span id + timestamp).
+printf '%s\n' "$MARKERS" | while IFS= read -r MARKER; do
+  [ -z "$MARKER" ] && continue
+  RUN_ID="$(printf '%s' "$MARKER" | sed -E 's/.*\[macf-route:([0-9]+):([a-z0-9-]+)\].*/\1/')"
+  AGENT="$(printf '%s' "$MARKER" | sed -E 's/.*\[macf-route:([0-9]+):([a-z0-9-]+)\].*/\2/')"
+
+  # Nanosecond epoch. `date +%s%N` is GNU-only (substrate is Linux); on a BSD/mac
+  # date that prints a literal `N`, fall back to seconds×1e9.
+  NOW="$(date +%s%N 2>/dev/null || true)"
+  case "$NOW" in
+    *N|'' ) NOW="$(( $(date +%s) * 1000000000 ))" ;;
+  esac
+  TID="$(openssl rand -hex 16)"
+  SID="$(openssl rand -hex 8)"
+
+  # Identity on resource attrs (matches the collector's resource/paper-dims +
+  # the `{resource."gen_ai.agent.name"=…}` TraceQL); correlation on span attrs.
+  curl -sf -m 3 -X POST "${BASE}/v1/traces" \
+    -H 'Content-Type: application/json' --data-binary @- <<JSON >/dev/null \
+    || echo "WARN: turn_processed span emit failed (endpoint=${BASE}/v1/traces run=${RUN_ID} agent=${AGENT})" >&2
+{"resourceSpans":[{"resource":{"attributes":[
+  {"key":"service.name","value":{"stringValue":"${OTEL_SERVICE_NAME:-macf-agent}"}},
+  {"key":"gen_ai.agent.name","value":{"stringValue":"${AGENT}"}},
+  {"key":"service.namespace","value":{"stringValue":"macf"}}
+]},"scopeSpans":[{"scope":{"name":"macf.hook"},"spans":[{
+  "traceId":"${TID}","spanId":"${SID}","name":"turn_processed","kind":1,
+  "startTimeUnixNano":"${NOW}","endTimeUnixNano":"${NOW}",
+  "attributes":[{"key":"routed_run_id","value":{"stringValue":"${RUN_ID}"}},
+    {"key":"agent","value":{"stringValue":"${AGENT}"}}],"status":{"code":1}}]}]}]}
+JSON
+done
+
+exit 0