@groundnuty/macf 0.2.36 → 0.2.38

package/scripts/check-auditor-never-acts.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+#
+# check-auditor-never-acts.sh — Claude Code PreToolUse hook that blocks
+# state-mutating `gh` ops (`gh pr merge`, `gh issue close`, `gh pr close`)
+# when the active identity is the AUDITOR (`MACF_AGENT_ROLE=auditor`), while
+# leaving the propose verbs (`gh issue/pr create|comment`) and all reads
+# untouched. Structurally enforces the auditor's "never-acts" boundary per
+# DR-026 (the auditor — self-evolving coordination governance): the auditor
+# is write-PROPOSALS-only; it opens issues/PRs and comments, but never merges
+# or closes — those acts route to a non-auditor implementer / the operator.
+#
+# Why structural and not permission-based: a GitHub App's `pull_requests:write`
+# permission grants merge+close TOGETHER with open-PR; there is no "open-a-PR-
+# but-not-merge" permission scope to express. The never-acts boundary therefore
+# has to be enforced at tool-call time, in the same family as the sibling
+# `check-*.sh` hooks (#140 token / #244+#272 mention / #270 lgtm / #431 close /
+# #489 attribution).
+#
+# Hook contract (PreToolUse): JSON on stdin, exit 0 = allow, exit 2 = block
+# (stderr is fed back to Claude as the error). Same shape as #140's
+# check-gh-token.sh + #270's check-lgtm-gate.sh.
+#
+# Inert for every NON-auditor identity (exit 0 before any parsing) — this is
+# the load-bearing gate that makes fleet-wide distribution safe: shipping this
+# hook to every workspace via `macf init` / `macf update` is a no-op everywhere
+# except the auditor, so code-agent / science-agent / cv-* keep their full
+# `gh` surface unchanged.
+#
+# Override: MACF_SKIP_AUDITOR_ACT_CHECK=1 bypasses (for a sanctioned exception
+# — e.g. the operator explicitly authorizing the auditor to perform a one-off
+# merge/close). Consistent with MACF_SKIP_TOKEN_CHECK / MACF_SKIP_LGTM_CHECK /
+# MACF_SKIP_CLOSE_CHECK / MACF_SKIP_ATTRIBUTION_CHECK in the sister hooks.
+#
+# Refs: groundnuty/macf#499 (this hook); DR-026 §1/§4 (auditor never-acts
+#       boundary; PROPOSED via #495); #140 / #244+#272 / #270 / #431 / #489
+#       (sister Path-2 hooks).
+set -uo pipefail
+
+# Defense-in-depth: any unexpected error past this point must NOT brick the
+# harness. We use `set -uo pipefail` (NOT `-e`) so commands that fail are
+# handled explicitly; this trap is a final safety net for a genuinely
+# unexpected fault — fail open (allow).
+trap 'exit 0' ERR
+
+# 1. Operator override first — cheapest exit. No stdin read, no parsing.
+if [[ "${MACF_SKIP_AUDITOR_ACT_CHECK:-}" == "1" ]]; then
+  exit 0
+fi
+
+# 2. Inert for every non-auditor identity. This is the load-bearing gate —
+#    when the active role isn't the auditor, the hook does nothing, so it is
+#    safe to distribute to every workspace. `MACF_AGENT_ROLE` is exported by
+#    claude.sh (env-files.ts) as the agent's role.
+if [[ "${MACF_AGENT_ROLE:-}" != "auditor" ]]; then
+  exit 0
+fi
+
+# 3. Read the PreToolUse payload. Fall through to allow on parse error — a
+#    broken hook must not brick the harness. Same defense-in-depth as
+#    check-gh-token.sh / check-lgtm-gate.sh.
+INPUT_JSON="$(cat 2>/dev/null || echo "")"
+COMMAND="$(jq -r '.tool_input.command // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+
+if [[ -z "$COMMAND" ]]; then
+  # No command extractable — allow (defense-in-depth).
+  exit 0
+fi
+
+# 4. Is this a `gh` invocation at all? Reuse the wrapper-aware GH_PATTERN +
+#    SHELL_C_PATTERN from check-gh-token.sh so `sudo gh`, `env X= gh`,
+#    `bash -c "gh …"`, and chained `&& gh` forms all count. If it's not a gh
+#    command, there is nothing for this hook to gate — allow.
+GH_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:]]'
+SHELL_C_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:]]'
+
+if [[ ! "$COMMAND" =~ $GH_PATTERN ]] && [[ ! "$COMMAND" =~ $SHELL_C_PATTERN ]]; then
+  # Not a gh command — allow.
+  exit 0
+fi
+
+# 5. Is the command one of the BLOCKED acting-verbs? Each op is matched two
+#    ways, mirroring check-lgtm-gate.sh's merge match: a WRAPPER pattern
+#    (sudo / env VAR= / watch / nice / chained-leadin `;|&` / inline VAR=)
+#    and a SHELL_C pattern (`bash -c "gh pr merge …"` and variants). Both
+#    anchor the `gh <noun> <verb>` substring and end on a whitespace-or-EOL
+#    boundary so e.g. `gh pr merge` matches but a hypothetical
+#    `gh pr merge-base` does NOT (exact-subcommand match).
+#
+#    ── BLOCKED acting-verbs (DENYLIST; intentionally minimal) ──────────────
+#    This is a denylist of STATE-MUTATING acts. The propose verbs
+#    (`gh issue create`, `gh pr create`, `gh issue comment`, `gh pr comment`)
+#    are deliberately ABSENT — the auditor is write-proposals-only, so those
+#    must fall through to the allow at the bottom. To extend the boundary
+#    (e.g. block `gh issue edit` of another agent's issue), add a `<noun> <verb>`
+#    entry to BLOCKED_VERBS below; keep the propose verbs out.
+#
+#      gh pr merge     — merging a PR is an act, not a proposal
+#      gh issue close  — closing an issue is an act (reporter-owns-closure)
+#      gh pr close     — closing a PR is an act
+BLOCKED_VERBS=(
+  'pr merge'
+  'issue close'
+  'pr close'
+)
+
+# Build the wrapper + shell-c regexes for a given `<noun> <verb>` and test the
+# command against both. Echoes the canonical `gh <noun> <verb>` label on a hit.
+_match_blocked_verb() {
+  local noun_verb="$1"        # e.g. "pr merge"
+  local cmd="$2"
+  # Translate the space in "<noun> <verb>" into the whitespace-class form.
+  local nv="${noun_verb/ /[[:space:]]+}"
+  local wrapper_pat="(^|[[: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:]]+${nv}([[:space:]]|$)"
+  local shell_c_pat="(^|[[: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:]]+${nv}([[:space:]]|$)"
+  if [[ "$cmd" =~ $wrapper_pat ]] || [[ "$cmd" =~ $shell_c_pat ]]; then
+    echo "gh ${noun_verb}"
+    return 0
+  fi
+  return 1
+}
+
+BLOCKED_OP=""
+for verb in "${BLOCKED_VERBS[@]}"; do
+  if hit="$(_match_blocked_verb "$verb" "$COMMAND")"; then
+    BLOCKED_OP="$hit"
+    break
+  fi
+done
+
+if [[ -z "$BLOCKED_OP" ]]; then
+  # 6. Not a blocked acting-verb — the propose verbs (gh issue/pr create,
+  #    gh issue/pr comment) and all reads fall through here. Write-proposals-
+  #    only is the auditor's permitted power. Allow.
+  exit 0
+fi
+
+# Blocked acting-verb under the auditor identity — block LOUD.
+cat >&2 <<ERR
+BLOCKED by MACF auditor-never-acts hook: the AUDITOR is write-PROPOSALS-only and
+must never perform a state-mutating act. The command you ran is a \`${BLOCKED_OP}\`,
+which closes/merges a resource — that is an ACT, not a proposal.
+
+Command: ${COMMAND}
+Blocked op: ${BLOCKED_OP}
+
+Per DR-026 §1/§4 (the auditor — self-evolving coordination governance), the
+auditor opens issues + PRs and comments to PROPOSE changes, but the merge/close
+ACT belongs to a non-auditor implementer (code-agent / science-agent) or the
+operator. This boundary is structural because a GitHub App's
+\`pull_requests:write\` permission grants merge+close together with open-PR —
+there is no "open-a-PR-but-not-merge" scope to express it, so the hook enforces
+it at tool-call time.
+
+Fix — route the act to a non-auditor identity:
+  - For a merge: @mention the PR's implementer on the issue thread; they merge
+    after the LGTM gate, per coordination.md / pr-discipline.md.
+  - For a close: @mention the issue's reporter; reporter-owns-closure
+    (coordination.md §Issue Lifecycle 1) — they close after verifying.
+  Leave the auditor's role to the PROPOSAL (the issue / PR / comment) you
+  already created.
+
+Override (ONLY for an operator-sanctioned exception):
+  export MACF_SKIP_AUDITOR_ACT_CHECK=1
+
+Refs: groundnuty/macf#499 (this hook); DR-026 §1/§4 (auditor never-acts).
+ERR
+exit 2

package/scripts/check-gh-attribution.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+#
+# check-gh-attribution.sh — Claude Code PostToolUse hook that, AFTER a
+# `gh`-write Bash op, verifies the just-written GitHub resource (issue /
+# PR / comment) was authored by the BOT, not the operator's user account.
+# A user-attributed write is the silent-fallback Instance-12 attribution
+# trap: the `gh` call fell back to stored `gh auth login` (user) because
+# GH_TOKEN was empty / a `ghp_`/`gho_`/`ghu_` user token / the literal
+# string "null", and nothing surfaced the mismatch at the time. The
+# #140 PreToolUse `check-gh-token.sh` catches the *missing-bot-token*
+# shape BEFORE the call; this hook is the result-invariant backstop that
+# catches a slipped write AFTER the fact by reading who actually authored
+# the resource on GitHub.
+#
+# Hook contract (PostToolUse): JSON on stdin, exit 0 = ok. PostToolUse
+# CANNOT block (the tool already ran) — the loud signal is `exit 2` with a
+# multi-line stderr message, which Claude Code surfaces back to Claude.
+# Read both the newer (`.tool_output.stdout`) and older
+# (`.tool_response.stdout` / `.tool_response`) output shapes defensively.
+#
+# Posture: FAIL-OPEN. `set -uo pipefail` (NOT `-e`) — every uncertain
+# branch (no URL, gh failure, can't parse, can't resolve expected login)
+# exits 0. A false WARN is more costly than a missed one here: the call
+# already happened, and the operator may be running a knowingly
+# user-attributed op. Only a CONFIRMED user-authored write fires `exit 2`.
+#
+# Override: MACF_SKIP_ATTRIBUTION_CHECK=1 bypasses (intentional
+# user-attributed ops, e.g. an onboarding `gh` call before the bot token
+# is wired). Consistent with MACF_SKIP_TOKEN_CHECK / MACF_SKIP_CLOSE_CHECK
+# in the sister hooks.
+#
+# Refs: groundnuty/macf#489 (this hook); silent-fallback-hazards.md
+#       Instance 12; coordination.md §Token & Git Hygiene (the attribution
+#       trap); #140 / #244+#272 / #270 / #431 (sister Path-2 hooks).
+set -uo pipefail
+
+# Cheap exit on operator override — no stdin read, no parsing.
+if [[ "${MACF_SKIP_ATTRIBUTION_CHECK:-}" == "1" ]]; then
+  exit 0
+fi
+
+# Defense-in-depth: any unexpected error past this point must NOT brick the
+# harness. We already use `set -uo pipefail` (no `-e`) so commands that fail
+# are handled explicitly; this trap is a final safety net for a genuinely
+# unexpected fault (e.g. a bash internal error) — fail open.
+trap 'exit 0' ERR
+
+# Read the PostToolUse payload. Fall through to allow on parse error.
+INPUT_JSON="$(cat)"
+COMMAND="$(jq -r '.tool_input.command // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+[[ -z "$COMMAND" ]] && exit 0
+
+# ── Is this a gh-write op that produces an attributable resource? ─────────
+# Match the write subcommands whose output carries a resource/comment URL:
+#   gh issue comment / gh pr comment   → posts a comment
+#   gh issue create  / gh pr create    → creates the resource
+#   gh issue close … --comment         → posts a closing comment
+#   gh pr close    … --comment         → posts a closing comment
+# A bare `gh issue close` (no --comment) writes nothing attributable → skip.
+# This is a RESULT check (not a blocker), so a simple wrapper-tolerant
+# `grep -qE` over the raw command suffices — we don't need the airtight
+# bypass-resistant regex the PreToolUse blockers carry.
+is_gh_write() {
+  local cmd="$1"
+  if grep -qiE 'gh[[:space:]]+(issue|pr)[[:space:]]+comment([[:space:]]|$)' <<<"$cmd"; then
+    return 0
+  fi
+  if grep -qiE 'gh[[:space:]]+(issue|pr)[[:space:]]+create([[:space:]]|$)' <<<"$cmd"; then
+    return 0
+  fi
+  # close … --comment (the --comment may appear anywhere after the verb)
+  if grep -qiE 'gh[[:space:]]+(issue|pr)[[:space:]]+close([[:space:]]|$)' <<<"$cmd" \
+     && grep -qiE '(^|[[:space:]])--comment([[:space:]]|=|$)' <<<"$cmd"; then
+    return 0
+  fi
+  return 1
+}
+is_gh_write "$COMMAND" || exit 0
+
+# ── Extract the resource URL from the tool output ─────────────────────────
+# `gh issue create` / `gh pr create` print the new URL on stdout; `gh issue
+# comment` / `gh pr comment` print the comment URL (…#issuecomment-<id>).
+# Read both PostToolUse output shapes (newer `.tool_output.stdout`, older
+# `.tool_response.stdout`, oldest `.tool_response` as a raw string).
+OUTPUT="$(jq -r '.tool_output.stdout // .tool_response.stdout // .tool_response // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+[[ -z "$OUTPUT" ]] && exit 0
+
+URL="$(grep -oE 'https://github\.com/[A-Za-z0-9._-]+/[A-Za-z0-9._-]+/(issues|pull)/[0-9]+(#issuecomment-[0-9]+)?' <<<"$OUTPUT" | head -1 || true)"
+# No URL in output (e.g. `--json` suppressed it, or output was discarded) →
+# fail open. We can't verify what we can't see.
+[[ -z "$URL" ]] && exit 0
+
+# ── Parse the URL → owner / repo / kind / number / optional comment-id ────
+# Form: https://github.com/<owner>/<repo>/(issues|pull)/<N>[#issuecomment-<id>]
+URL_PATH="${URL#https://github.com/}"
+OWNER="$(cut -d/ -f1 <<<"$URL_PATH")"
+REPO="$(cut -d/ -f2 <<<"$URL_PATH")"
+KIND="$(cut -d/ -f3 <<<"$URL_PATH")"          # issues | pull
+NUM_AND_FRAG="$(cut -d/ -f4 <<<"$URL_PATH")"  # <N> | <N>#issuecomment-<id>
+NUM="${NUM_AND_FRAG%%#*}"
+COMMENT_ID=""
+if [[ "$NUM_AND_FRAG" == *"#issuecomment-"* ]]; then
+  COMMENT_ID="${NUM_AND_FRAG##*#issuecomment-}"
+fi
+# Sanity — if any required piece is missing/odd, fail open.
+[[ -z "$OWNER" || -z "$REPO" || -z "$KIND" || -z "$NUM" ]] && exit 0
+
+# ── Build the ACTUAL-resource API path ────────────────────────────────────
+# Comment-id present → both issue AND pr comments live under the issues
+# comments namespace; else a PR → pulls/<N>; else an issue → issues/<N>.
+if [[ -n "$COMMENT_ID" ]]; then
+  API_PATH="/repos/${OWNER}/${REPO}/issues/comments/${COMMENT_ID}"
+elif [[ "$KIND" == "pull" ]]; then
+  API_PATH="/repos/${OWNER}/${REPO}/pulls/${NUM}"
+else
+  API_PATH="/repos/${OWNER}/${REPO}/issues/${NUM}"
+fi
+
+# ── Query the author (short timeout; one brief retry for API consistency) ─
+# The resource was JUST created, so a first read can occasionally race the
+# write through GitHub's read replicas. One `sleep 1` retry handles that
+# without materially delaying the turn. gh failure / empty → fail open.
+query_author() {
+  GH_PAGER= gh api "$API_PATH" --jq '{login: .user.login, type: .user.type}' 2>/dev/null
+}
+RESP="$(query_author || true)"
+if [[ -z "$RESP" ]]; then
+  sleep 1
+  RESP="$(query_author || true)"
+fi
+[[ -z "$RESP" ]] && exit 0
+
+ACTUAL_LOGIN="$(jq -r '.login // ""' <<<"$RESP" 2>/dev/null || echo "")"
+ACTUAL_TYPE="$(jq -r '.type // ""' <<<"$RESP" 2>/dev/null || echo "")"
+# Couldn't extract an author at all → fail open.
+[[ -z "$ACTUAL_LOGIN" ]] && exit 0
+
+# ── Resolve the EXPECTED bot login + whether it is AUTHORITATIVE ──────────
+# AUTHORITATIVE sources (a mismatch is a real trap, even vs a different Bot):
+#   1. $MACF_EXPECTED_BOT_LOGIN — explicit operator/test override.
+#   2. .macf/macf-agent.json `.github_app.bot_login` — the App's real bot login
+#      (App slug + `[bot]`), written by macf init/doctor (DR-028). Authoritative.
+# NON-authoritative HINT:
+#   3. .macf/macf-agent.json `.agent_name` / `.app_name` — a derived guess that
+#      assumes agent_name == App slug, which is NOT always true (macf#535: the
+#      auditor's agent_name is "auditor" but its App slug is macf-auditor-agent).
+#      A mismatch on this guess is trapped ONLY when a User authored it (the
+#      Instance-12 trap); a Bot author that just doesn't match the guess is the
+#      name!=slug case and is allowed (no false positive).
+#   4. empty — fall back to the type-based check below.
+EXPECTED_LOGIN="${MACF_EXPECTED_BOT_LOGIN:-}"
+EXPECTED_AUTHORITATIVE=0
+[[ -n "$EXPECTED_LOGIN" ]] && EXPECTED_AUTHORITATIVE=1
+if [[ -z "$EXPECTED_LOGIN" ]]; then
+  AGENT_JSON="${CLAUDE_PROJECT_DIR:-.}/.macf/macf-agent.json"
+  if [[ -f "$AGENT_JSON" ]]; then
+    BOT_LOGIN="$(jq -r '.github_app.bot_login // .bot_login // ""' "$AGENT_JSON" 2>/dev/null || echo "")"
+    if [[ -n "$BOT_LOGIN" ]]; then
+      # Append `[bot]` exactly once (tolerate a config that already carries it).
+      EXPECTED_LOGIN="${BOT_LOGIN%"[bot]"}[bot]"
+      EXPECTED_AUTHORITATIVE=1
+    else
+      AGENT_NAME="$(jq -r '.agent_name // .app_name // ""' "$AGENT_JSON" 2>/dev/null || echo "")"
+      if [[ -n "$AGENT_NAME" ]]; then
+        # Non-authoritative guess (see note above) — leave AUTHORITATIVE=0.
+        EXPECTED_LOGIN="${AGENT_NAME%"[bot]"}[bot]"
+      fi
+    fi
+  fi
+fi
+
+# Normalize a login for comparison: strip a leading `app/` prefix (gh's
+# GraphQL author.login carries `app/<name>`; the REST `.user.login` does
+# not) and lowercase. Echoes the normalized form.
+normalize_login() {
+  local l="$1"
+  l="${l#app/}"
+  echo "${l,,}"
+}
+
+NORM_ACTUAL="$(normalize_login "$ACTUAL_LOGIN")"
+
+# ── Decide: OK vs MISMATCH ────────────────────────────────────────────────
+MISMATCH=0
+if [[ -n "$EXPECTED_LOGIN" ]]; then
+  NORM_EXPECTED="$(normalize_login "$EXPECTED_LOGIN")"
+  if [[ "$NORM_ACTUAL" == "$NORM_EXPECTED" ]]; then
+    exit 0
+  fi
+  # Mismatch. Trap if the expectation is AUTHORITATIVE (env / bot_login — a
+  # different author, even a Bot, is wrong), OR a User authored it (the
+  # Instance-12 trap, regardless of source). A Bot author that only mismatches
+  # a NON-authoritative agent_name guess is the name!=slug case (macf#535) → ok.
+  if [[ "$EXPECTED_AUTHORITATIVE" == "1" || "$ACTUAL_TYPE" != "Bot" ]]; then
+    MISMATCH=1
+  else
+    exit 0
+  fi
+else
+  # No expected login known — best verifiable signal is the author TYPE.
+  # A Bot authored it → trust it (some bot posted; correct by design).
+  # A User authored it → the Instance-12 trap (a human account wrote it).
+  if [[ "$ACTUAL_TYPE" == "Bot" ]]; then
+    exit 0
+  fi
+  MISMATCH=1
+fi
+
+[[ "$MISMATCH" -ne 1 ]] && exit 0
+
+# ── MISMATCH → loud warning to stderr, then exit 2 ────────────────────────
+EXPECTED_LINE="(unknown — set \$MACF_EXPECTED_BOT_LOGIN or .macf/macf-agent.json)"
+if [[ -n "$EXPECTED_LOGIN" ]]; then
+  EXPECTED_LINE="$EXPECTED_LOGIN"
+fi
+
+cat >&2 <<ERR
+WARNING (MACF attribution-result check): the GitHub resource you just wrote
+appears to be authored by the WRONG account — the silent-fallback Instance-12
+attribution trap (a \`gh\` write fell back to the operator's USER auth instead
+of the bot installation token).
+
+Resource:        ${URL}
+Authored by:     ${ACTUAL_LOGIN} (type: ${ACTUAL_TYPE:-unknown})
+Expected (bot):  ${EXPECTED_LINE}
+
+The tool already ran — this is a PostToolUse check, so the resource is live on
+GitHub under the wrong attribution. Cross-agent routing keys off the bot login;
+a user-attributed comment/issue/PR is invisible to peers and breaks the
+reporter-owns-closure + @mention-routing contracts.
+
+Repair:
+  1. Refresh the bot token (fail-loud helper), THEN re-do the op as the bot:
+
+       GH_TOKEN=\$("\$MACF_WORKSPACE_DIR/.claude/scripts/macf-gh-token.sh" \\
+         --app-id "\$APP_ID" --install-id "\$INSTALL_ID" --key "\$KEY_PATH") || exit 1
+       export GH_TOKEN
+
+  2. If the resource has NOT been replied-to yet, delete the mis-attributed
+     write and re-post it as the bot (clean correction).
+  3. If it HAS already been replied-to / acted-on, do NOT delete — post a
+     short clarify-forward correction comment AS THE BOT noting the prior
+     write was mis-attributed, so the thread stays coherent.
+
+Verify your identity any time:
+  GH_TOKEN=\$GH_TOKEN "\$MACF_WORKSPACE_DIR/.claude/scripts/macf-whoami.sh"
+
+Override (ONLY for intentional user-attributed ops, e.g. onboarding):
+  export MACF_SKIP_ATTRIBUTION_CHECK=1
+
+Refs: groundnuty/macf#489 (this hook); silent-fallback-hazards.md Instance 12;
+coordination.md §Token & Git Hygiene.
+ERR
+exit 2

package/scripts/emit-turn-receipt.sh

@@ -43,7 +43,7 @@ MARKERS="$(printf '%s' "$PROMPT" | grep -oE '\[macf-route:[0-9]+:[a-z0-9-]+\]' |
 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="${OTEL_EXPORTER_OTLP_ENDPOINT:-http://orzech-dev-agents-monitoring.tail491af.ts.net:4318}"
 BASE="${BASE%/v1/traces}"
 
 # One independent span per distinct marker (own trace/span id + timestamp).

package/scripts/harvest-reflection.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# harvest-reflection.sh — Claude Code PreCompact hook that harvests a *staged*
+# reflection the agent maintains (`.claude/.macf/reflections/pending.json`),
+# wraps it in the versioned reflection-schema envelope (groundnuty/macf#500,
+# DR-026 F2 — see @groundnuty/macf-core `reflection.ts`), appends it as one
+# line to a local JSONL ledger, and clears the stage. Local + cheap; F4's
+# Monitor reads the ledger back.
+#
+# Hook contract (PreCompact): JSON on stdin carrying `session_id`,
+# `transcript_path?`, `cwd`, `hook_event_name="PreCompact"`, `trigger`
+# ("auto"|"manual"), `permission_mode`, `effort`. Registration is matcher-less.
+# `$CLAUDE_PROJECT_DIR` is available.
+#
+# MACF doctrine (DR-023 §UC-3): observational + NON-BLOCKING. This hook ALWAYS
+# `exit 0` — a non-zero exit would delay/block compaction and harm the operator.
+# Every risky step is guarded (`|| true`) so an internal failure still emits a
+# (possibly mechanical-only) record OR, worst case, exits 0 cleanly. There is
+# NO `exit 2` anywhere. Fast + local (<100ms target; 30s hard timeout); no
+# network.
+#
+# Override: MACF_SKIP_REFLECTION_HARVEST=1 bypasses (consistent with the
+# MACF_SKIP_* hook family).
+set -uo pipefail
+
+# Final safety net: any genuinely unexpected fault past this point must NOT
+# brick compaction. Fail open (exit 0), same posture as check-gh-attribution.sh.
+trap 'exit 0' ERR
+
+# Cheap operator override — no stdin read, no parsing.
+if [[ "${MACF_SKIP_REFLECTION_HARVEST:-}" == "1" ]]; then
+  exit 0
+fi
+
+# ── Read the PreCompact payload (all defensive: never fail on bad input) ──────
+INPUT_JSON="$(cat 2>/dev/null || echo '')"
+SESSION_ID="$(jq -r '.session_id // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+TRIGGER="$(jq -r '.trigger // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+PAYLOAD_CWD="$(jq -r '.cwd // ""' <<<"$INPUT_JSON" 2>/dev/null || echo "")"
+
+# `compaction_type` is the payload trigger when it's a known value, else null.
+# Emitted as a JSON literal for `--argjson`: a quoted string ("auto"/"manual")
+# or the bare null literal.
+case "$TRIGGER" in
+  auto|manual) COMPACTION_TYPE="\"$TRIGGER\"" ;;
+  *)           COMPACTION_TYPE="null" ;;
+esac
+
+# ── Resolve the reflections dir + the staged pending file ─────────────────────
+BASE_DIR="${CLAUDE_PROJECT_DIR:-$PAYLOAD_CWD}"
+[[ -z "$BASE_DIR" ]] && BASE_DIR="."
+DIR="$BASE_DIR/.claude/.macf/reflections"
+PENDING="$DIR/pending.json"
+mkdir -p "$DIR" 2>/dev/null || true
+
+# ── Agent identity from the claude.sh-exported env (graceful when unset) ──────
+AGENT_NAME="${MACF_AGENT_NAME:-}"
+AGENT_ROLE="${MACF_AGENT_ROLE:-}"
+PROJECT="${MACF_PROJECT:-}"
+# Derive the bot login from the agent name: `<name>[bot]`, or empty if unknown.
+if [[ -n "$AGENT_NAME" ]]; then
+  AGENT_LOGIN="${AGENT_NAME}[bot]"
+else
+  AGENT_LOGIN=""
+fi
+
+TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")"
+
+# ── Read the staged reflection fields (each defaulted if absent/invalid) ──────
+# Default to an empty stage object; only overwrite if pending.json is valid
+# JSON. This yields a mechanical-only record when there's no (or a broken)
+# stage — still emitted so the Monitor sees the compaction.
+STAGE_JSON='{}'
+if [[ -f "$PENDING" ]]; then
+  if _stage="$(jq -c '.' "$PENDING" 2>/dev/null)" && [[ -n "$_stage" ]]; then
+    STAGE_JSON="$_stage"
+  fi
+fi
+
+# ── Build the envelope record with jq, merging the staged fields ──────────────
+# Each staged array/string is defaulted inside jq so a partial stage is valid.
+# `--argjson compaction_type` carries either a quoted string ("auto"/"manual")
+# or the bare literal null.
+RECORD="$(
+  jq -cn \
+    --arg schema_version "1.0" \
+    --arg kind "macf.reflection" \
+    --arg name "$AGENT_NAME" \
+    --arg role "$AGENT_ROLE" \
+    --arg login "$AGENT_LOGIN" \
+    --arg project "$PROJECT" \
+    --arg session_id "$SESSION_ID" \
+    --arg timestamp "$TIMESTAMP" \
+    --argjson compaction_type "$COMPACTION_TYPE" \
+    --argjson stage "$STAGE_JSON" \
+    '{
+      schema_version: $schema_version,
+      kind: $kind,
+      agent: { name: $name, role: $role, login: $login },
+      project: $project,
+      session_id: $session_id,
+      timestamp: $timestamp,
+      trigger: "pre-compact",
+      compaction_type: $compaction_type,
+      observed_patterns:      ($stage.observed_patterns      // []),
+      breaches:               ($stage.breaches               // []),
+      rule_evolution_signals: ($stage.rule_evolution_signals // []),
+      unresolved:             ($stage.unresolved             // []),
+      synthesis:              ($stage.synthesis              // "")
+    }' 2>/dev/null || echo ""
+)"
+
+# If even the jq build failed, bail cleanly — never block compaction.
+[[ -z "$RECORD" ]] && exit 0
+
+# ── Append the single-line record to the per-session JSONL ledger ─────────────
+SAFE_SESSION="$SESSION_ID"
+[[ -z "$SAFE_SESSION" ]] && SAFE_SESSION="unknown-session"
+LEDGER="$DIR/${SAFE_SESSION}.jsonl"
+printf '%s\n' "$RECORD" >>"$LEDGER" 2>/dev/null || true
+
+# ── Clear the stage so the next session starts fresh ──────────────────────────
+printf '%s\n' '{}' >"$PENDING" 2>/dev/null || true
+
+exit 0