@groundnuty/macf 0.2.36 → 0.2.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundnuty/macf",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "Multi-Agent Coordination Framework CLI — coordinate Claude Code agents via GitHub. Installs as `macf` binary; use `macf init` to set up an agent workspace, `macf update` to refresh rules + version pins.",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@groundnuty/macf-core": "0.2.36",
+    "@groundnuty/macf-core": "0.2.37",
     "commander": "^14.0.3",
     "reflect-metadata": "^0.2.2",
     "zod": "^4.0.0"

package/plugin/rules/gh-token-attribution-traps.md

@@ -50,6 +50,10 @@ case "$TOKEN" in ghs_*) ;; *) echo "FATAL: bad token prefix" >&2; exit 1 ;; esac
 export GH_TOKEN="$TOKEN"
 ```
 
+**Why the bare `TOKEN=$(...)` + separate `export`, never `export GH_TOKEN=$(...)`:** `export` is a builtin whose own exit status (`0`) *replaces* the command-substitution's, so `export GH_TOKEN=$(helper) || exit 1` and `export GH_TOKEN=$(helper) && gh ...` both proceed even when the helper failed (ShellCheck SC2155). The failure only propagates from a **bare** assignment (`TOKEN=$(helper) || …`). This is load-bearing under GitHub's intermittent token-endpoint 401s: a refresh that can yield an empty token *without aborting* the dependent `gh` ops re-creates mode #3 (witnessed 2026-06-12 — `cv-architect` posted 4 comments as the operator under a transient 401).
+
+**The PreToolUse hook does NOT cover this.** `check-gh-token.sh` validates the *ambient* `GH_TOKEN` before the command runs, so an inline `export GH_TOKEN=$(...) && gh ...` (refresh-chain *or* file-cache read) reassigns the token *after* the hook has already passed — the hook is structurally blind to it (silent-fallback **Instance 12**, `silent-fallback-hazards.md`). Refresh in a **separate step** (to a pre-validated file, or a bare-assigned var with the checks above), never inline in the `gh` command. The durable structural cover is a result-invariant **PostToolUse** `author`-check (macf#489), not the PreToolUse precondition.
+
 ### 4. Wrong `gh auth` on the VM providing fallback
 
 Having `gh auth login` configured as a user account creates the fallback surface in #3. Even a "good" setup where the script is correct can hide a broken bot token because `gh` quietly uses the user auth.

package/plugin/rules/observability-wiring.md

@@ -13,7 +13,7 @@ Every MACF agent's `claude.sh` launcher exports the Claude Code native OpenTelem
 | `OTEL_TRACES_EXPORTER` | `otlp` | Emit traces. Without it, no spans even if master gate is on |
 | `OTEL_METRICS_EXPORTER` | `otlp` | Emit metrics. **Per-signal** — separate from traces |
 | `OTEL_LOGS_EXPORTER` | `otlp` | Emit logs. **Per-signal** — separate from traces |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` (default) | OTLP HTTP receiver. Override via `MACF_OTEL_ENDPOINT` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:14318` (macf canonical — the bare OTLP default `:4318` is overridden by `macf init`/`update`) | OTLP HTTP receiver. Override via `MACF_OTEL_ENDPOINT` |
 | `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | Wire protocol |
 | `OTEL_SERVICE_NAME` | `macf-agent-<name>` | All MACF agents grouped under one service.name family |
 | `OTEL_RESOURCE_ATTRIBUTES` | `gen_ai.agent.name=<name>,gen_ai.agent.role=<role>,service.namespace=macf` | Semconv-compliant resource attrs |
@@ -32,10 +32,10 @@ Per-workspace, two env knobs read at `macf init` / `macf update` time:
   - Deployment has no OTLP receiver running (no observability stack)
   - You want zero retry-spam from the exporter
   - Agent runs offline / on a host that can't reach the collector
-- `MACF_OTEL_ENDPOINT=http://central-host:4318` — overrides the default `http://localhost:4318`. Use when:
+- `MACF_OTEL_ENDPOINT=http://central-host:14318` — overrides the default `http://localhost:14318`. Use when:
   - The observability stack is on a different host (Tailscale tailnet, reverse proxy, central collector)
   - You're running multiple MACF deployments and want them all reporting to one collector
-  - The default port `4318` collides with another service on the agent's host (e.g., devops-toolkit's compose stack uses `:14318` for this reason)
+  - **Note:** the canonical macf-devops-toolkit k3d stack serves OTLP HTTP on `:14318` (the bare-SDK default `:4318` was retired 2026-04-25 after it collided with the prior compose stack and caused 34 min of zero-telemetry on CV agents — macf#282/#283). Use `:14318`, not `:4318`.
 
 To apply a knob: set the env var BEFORE running `macf update`. The launcher re-renders with the new state.
 

package/plugin/rules/reflection-staging.md

@@ -0,0 +1,65 @@
+# Reflection Staging (canonical, shared)
+
+**Maintain a staged reflection as you work. At compaction it is harvested automatically.** This file is the single source of truth for the reflection-staging discipline; it is copied into each agent workspace's `.claude/rules/` by `macf init` and refreshed by `macf update` / `macf rules refresh`. Do not edit workspace copies directly — edit the canonical file at `groundnuty/macf:packages/macf/plugin/rules/reflection-staging.md` and re-distribute.
+
+Applies to every MACF agent. The mechanism is local + cheap and never blocks compaction (DR-026 F2, groundnuty/macf#500).
+
+---
+
+## What this is
+
+You accumulate observations as you work — recurring patterns, canonical-rule breaches you committed or witnessed, signals that a rule should evolve, loose ends. Historically these lived in "remember to synthesize before compaction" / "codify at decision time" disciplines, which depended on you remembering to act at exactly the moment your context was about to be summarized away.
+
+This rule gives those disciplines a **structural home**: a single file you keep current as you go. They stop being "remember to do X at compaction" and become "keep `pending.json` current." At compaction, the `harvest-reflection.sh` PreCompact hook reads the staged file, wraps it in the versioned reflection envelope, appends it to a local per-session JSONL ledger, and clears the stage for the next session. You never run the harvest by hand — the hook fires on both auto-compaction and manual `/compact`.
+
+---
+
+## The staged file
+
+Maintain `.claude/.macf/reflections/pending.json` incrementally. It holds only the **protocol-signal fields** — the hook adds the envelope (`schema_version`, `kind`, agent identity, project, session id, timestamp, trigger, compaction type) at harvest time.
+
+```jsonc
+{
+  // Recurring behaviour / coordination dynamic / workflow shape worth surfacing.
+  "observed_patterns": [
+    { "pattern": "<short name>", "evidence": "<what you saw / a ref>", "tier_hint": "<where it might belong>" }
+  ],
+  // Canonical-rule breaches you committed or witnessed this session.
+  "breaches": [
+    { "rule": "<rule name>", "what": "<the breach>", "ref": "<issue/PR/commit/file:line>" }
+  ],
+  // Signals that a coordination rule should evolve (proposals for governance).
+  "rule_evolution_signals": [
+    { "signal": "<what changed/recurred>", "proposed_tier": "<suggested tier>", "rationale": "<why>" }
+  ],
+  // Loose ends to pick up next session.
+  "unresolved": [ "<string>", "<string>" ],
+  // One-paragraph free-form synthesis of the session.
+  "synthesis": "<prose>"
+}
+```
+
+Every field is optional. An empty `{}` (the cleared state) is valid — the hook still emits a **mechanical-only** record at compaction so the Monitor sees that a compaction happened. Arrays default to `[]`, `synthesis` to `""`.
+
+`observed_patterns[]` and `rule_evolution_signals[]` may carry an optional `key` field — reserved for deterministic cross-agent dedup later (additive; leave it out for now unless you have a stable key).
+
+## How to keep it current
+
+- **Append, don't wait.** When you notice a pattern, breach, or evolution signal mid-session, add it to the relevant array right then. Don't batch it for "later" — later is compaction, and the point is that the staging already happened.
+- **Edit the file directly** (`Read` then `Edit`/`Write`). It is plain JSON in your workspace; no command or tool call is needed.
+- **Keep `synthesis` a living summary.** Overwrite it as your understanding of the session firms up.
+- **Don't clear it yourself.** The harvest hook clears the stage after appending. If you clear it, the next compaction emits a mechanical-only record and your observations are lost.
+
+## Where it lands
+
+- Ledger: `.claude/.macf/reflections/<session_id>.jsonl` (one JSON object per line, schema-validated by `@groundnuty/macf-core` `ReflectionRecordSchema`).
+- The ledger is **local + observational** — DR-023 §UC-3 posture. The harvest never blocks compaction; an internal error fails open (`exit 0`).
+- Opt out of harvesting for a session with `MACF_SKIP_REFLECTION_HARVEST=1`.
+
+---
+
+## When to read vs. modify
+
+- **Read:** every session start. This rule defines how to stage your reflection.
+- **Modify:** never directly in workspace copies. Edit the canonical file and re-distribute via `macf update`.
+- **Disagree with a rule?** Open an issue on `groundnuty/macf` proposing the change, with rationale. Peer review applies.

package/plugin/rules/silent-fallback-hazards.md

@@ -4,7 +4,7 @@
 
 > **Workspaces without full `macf init`** (e.g. `groundnuty/macf` itself, or any Claude Code workspace operated by a bot that isn't a MACF-registered agent) can still get this canonical rule via `macf rules refresh --dir <workspace>`. Same copy, no App credentials or registry required.
 
-This rule names the CLASS so agents recognize the shape on first encounter rather than re-discovering each instance from scratch. Ten active instances are documented below as worked examples spanning different architectural layers (identity, parsing, TUI binding, observability routing, config substitution, multi-agent coordination protocol, metric-instrumentation lifecycle, observability-endpoint routing, release-pipeline-partial-publish, third-party-action retry-exhaustion). (Instance 10 — a legacy substrate-routing receipt-gap — was retired 2026-06-07; its number is kept, not reused.) Nine of ten active instances have structural defenses applied or in flight — the pattern of defense generalizes alongside the pattern of hazard.
+This rule names the CLASS so agents recognize the shape on first encounter rather than re-discovering each instance from scratch. Eleven active instances are documented below as worked examples spanning different architectural layers (identity, parsing, TUI binding, observability routing, config substitution, multi-agent coordination protocol, metric-instrumentation lifecycle, observability-endpoint routing, release-pipeline-partial-publish, third-party-action retry-exhaustion, credential-refresh temporal-binding). (Instance 10 — a legacy substrate-routing receipt-gap — was retired 2026-06-07; its number is kept, not reused.) Ten of eleven active instances have structural defenses applied or in flight — the pattern of defense generalizes alongside the pattern of hazard.
 
 Instance 9 is annotated as **sister-shape** (failure correctly surfaced + partial side-effect breaks retry idempotency) — listed here for cross-reference convenience but warrants a sibling canonical rule (`partial-side-effect-hazards.md`) if more instances surface. The two classes share "multi-step pipeline where consumer assumes atomicity" but the failure surface differs: silent-fallback hides at the API boundary; partial-side-effect surfaces loudly but persists semi-state.
 
@@ -203,6 +203,22 @@ Generalizes to any retry-wrapping action: assert the result-invariant the connec
 
 ---
 
+### Instance 12 — PreToolUse credential-guard validates the *ambient* token, blind to inline mid-command reassignment
+
+**Surface:** the #140 `check-gh-token.sh` PreToolUse hook, plus any refresh idiom that reassigns `GH_TOKEN` *inline within the same Bash command* as the `gh` calls it is meant to guard (`export GH_TOKEN=$(gh token generate ... | jq -r .token) && gh ...`; `export GH_TOKEN=$(cat tok.txt) && gh ...`).
+
+**Failure shape:** the hook validates `GH_TOKEN` purely from the **ambient environment present *before* the command runs** (`GH_TOKEN_VALUE="${GH_TOKEN:-}"`, then the `^ghs_[A-Za-z0-9_]+$` predicate). It never parses the command string for an inline `GH_TOKEN=` / `export GH_TOKEN=$(...)` reassignment. Agents launch with a valid `ghs_` token in ambient env, so the hook **passes and exits 0** — *then* the inline `$(...)` runs, and on an intermittent GitHub-side 401 the naive `| jq` (no `set -o pipefail`) emits empty/`null`, clobbering `GH_TOKEN` to empty **after the hook has already returned**. The chained `gh` calls fall back to the stored `gh auth login` user. **The recommended refresh-chain bypasses its own guard.** The hook only blocks when the ambient is *already* bad — the exact case the rules tell agents not to rely on; in the normal regime (valid ambient) it is a pass-through no-op for every inline-refresh shape, including the file-cache read.
+
+Two adjacent sub-failures: **(a)** `export X=$(helper)` masks a fail-loud helper's non-zero exit, because `export` is a builtin whose own exit `0` replaces the substitution's (ShellCheck SC2155) — so `pipefail` / a fail-loud helper *alone* is insufficient; only `GH_TOKEN=$(helper) || exit 1` (bare assignment + explicit abort) short-circuits the `&&`. **(b)** A redirect `helper > tok.txt` truncates the cache file *before* the helper runs, so a 401 leaves an *empty* file for the next read — write atomic-validated (`mktemp` + `grep ghs_` + `mv`) instead.
+
+**Recurrence:** First confirmed — `macf-cv-architect` 2026-06-12 (4 issue/PR comments posted as the operator under an intermittent GitHub-side 401). Verified by 3-lens adversarial review (source-code / shell-mechanism / alternative-cause, 3-0 survived). Generalizes to every agent's inline / file-cache refresh form; the substrate workbenches additionally had the footgun *taught* by an unrefreshed bootstrap `gh-token-refresh.md` that `macf update` does not distribute.
+
+**Defense status:** layered. **(1) DOC (shipped):** de-footgun `gh-token-refresh.md` (+ `agent-identity.md`) — fail-loud `GH_TOKEN=$(helper) || exit 1`, no inline-refresh, atomic-validated file-cache; this rule's sister `gh-token-attribution-traps.md` strengthened with the export-mask. **(2) STRUCTURAL — the load-bearing fix, Pattern A:** a result-invariant **PostToolUse** check asserting the just-written resource's `author` == expected bot login (`macf-whoami.sh` / `--json author`) — the only level that sees through inline-clobber, file-cache-staleness, *and* future bypass shapes, because it checks what was actually posted, not the command-string shape (filed macf#489). **(3) Decided-against:** teaching the PreToolUse hook to detect inline `GH_TOKEN=$(...)` reassignment — brittle regex over arbitrary shell, and the export-mask makes the safe-predicate subtle.
+
+**Class lesson:** a structural defense that validates a precondition at the **wrong temporal level** — pre-command ambient state instead of the post-mutation runtime value — provides no protection in exactly the regime it was built for. **Result-invariant assertion at the boundary (Pattern A) is the temporal-level-agnostic fix; command-string precondition checks are not.** This is the clearest case yet of *why* Pattern A bears the most weight in this rule.
+
+---
+
 ## How to recognize the class on first encounter
 
 When investigating a "the operation completed but the outcome is wrong" incident, suspect silent-fallback if ANY of:
@@ -358,10 +374,11 @@ For coordination-system safety analysis: this is a class of hazards multi-agent
 | 8 — OTLP endpoint silent-drop | Observability-endpoint routing | Five-surface defense: CLI release-discipline + substrate testers env-override + canonical template `:14318` default + cluster-side compat port-map + agent-process `doctor-otel.sh` Pattern A | Pattern A (composite — first multi-architectural-layer case in this rule; instances 1-7 have single-pattern defenses) |
 | 9 — Sigstore TLOG orphans on failed npm publish (sister-class) | npm publish + sigstore attestation pipeline | Three-defense composite: bump-version recovery (DR-022 Amendment L) + pre-flight registry-collision check (Pattern D analog, macf#380) + TLOG-state observability (devops-toolkit#74+#77 Grafana dashboard live) | Pattern D analog (pre-flight precheck) + recovery-procedure-codification |
 | 11 — Third-party retry-wrapping action exits 0 on retry-exhaustion | Consumer-CI connect/auth via third-party action (tailnet, OTLP, cloud-auth, registry-login) | SHIPPED — "Verify <resource> is up" step immediately after the connect asserts the connection's result-invariant (e.g. `tailscale status` `BackendState == "Running"`) + fails LOUD; never trusts the action's exit code about its own retry exhaustion (macf#461) | Pattern A (post-connect result-invariant assert) + Pattern D flavor (precheck-before-downstream) |
+| 12 — PreToolUse credential-guard validates ambient token, blind to inline reassignment | gh-token PreToolUse hook + inline `export GH_TOKEN=$(...) && gh` (refresh-chain or file-cache) | DOC shipped (de-footgun `gh-token-refresh.md` + atomic-validated cache) + STRUCTURAL in flight (Pattern A result-invariant PostToolUse whoami post-check, macf#489) | Pattern A (result-invariant post-check — a wrong-temporal-level precondition can't see the inline clobber) |
 
-Nine of ten active instances have structural defense applied or shipped. Defense patterns (A, B, C, D, E) generalize across instances — they're reusable defense templates, not case-specific fixes. **Pattern A (result-invariant assertion at the boundary) bears the most weight** — it's the structural defense for instances 4, 7, 8, AND 11 (4 of 10), each at a different architectural boundary (logs pipeline, metric counter, observability endpoint, third-party-action connect-verify). Instance 8's five-surface defense topology (consumer canonical + cluster-side compat port-map + concrete Pattern A impl) demonstrates that structural defense at the observability-pipeline-class can compose across architectural layers — the canonical-distribution layer + the cluster-infrastructure layer + the assertion-script layer all reinforce each other rather than substituting for each other. Instance 9 demonstrates that the Pattern D template generalizes from workflow-secrets-prechecks to release-pipeline-prechecks AND that recovery-procedure-codification (DR-022 Amendment L's bump-version-not-tag-retry) is its own defense category — distinct from detection-pre-merge defenses (Patterns A/B/D) and discrimination-at-receiver defenses (Pattern E).
+Ten of eleven active instances have structural defense applied, shipped, or in flight. Defense patterns (A, B, C, D, E) generalize across instances — they're reusable defense templates, not case-specific fixes. **Pattern A (result-invariant assertion at the boundary) bears the most weight** — it's the structural defense for instances 4, 7, 8, 11, AND 12 (5 of 11), each at a different architectural boundary (logs pipeline, metric counter, observability endpoint, third-party-action connect-verify, credential-refresh temporal-binding). Instance 8's five-surface defense topology (consumer canonical + cluster-side compat port-map + concrete Pattern A impl) demonstrates that structural defense at the observability-pipeline-class can compose across architectural layers — the canonical-distribution layer + the cluster-infrastructure layer + the assertion-script layer all reinforce each other rather than substituting for each other. Instance 9 demonstrates that the Pattern D template generalizes from workflow-secrets-prechecks to release-pipeline-prechecks AND that recovery-procedure-codification (DR-022 Amendment L's bump-version-not-tag-retry) is its own defense category — distinct from detection-pre-merge defenses (Patterns A/B/D) and discrimination-at-receiver defenses (Pattern E).
 
-The breadth of layers spanned by 5 different defense patterns (identity, parsing, TUI binding, observability routing, config substitution, multi-agent coordination protocol, metric-instrumentation lifecycle, observability-endpoint routing, release-pipeline-partial-publish, third-party-action retry-exhaustion) is independent evidence that the hazard CLASS is real. If silent-fallback was a single-instance accident, no defense pattern would emerge. **Pattern A's recurrence across 3 different observability boundaries (logs / metrics / endpoint) is the strongest signal that result-invariant assertion is the load-bearing structural-defense template for the entire observability-pipeline-class** of silent fallback.
+The breadth of layers spanned by 5 different defense patterns (identity, parsing, TUI binding, observability routing, config substitution, multi-agent coordination protocol, metric-instrumentation lifecycle, observability-endpoint routing, release-pipeline-partial-publish, third-party-action retry-exhaustion, credential-refresh temporal-binding) is independent evidence that the hazard CLASS is real. If silent-fallback was a single-instance accident, no defense pattern would emerge. **Pattern A's recurrence across 3 different observability boundaries (logs / metrics / endpoint) is the strongest signal that result-invariant assertion is the load-bearing structural-defense template for the entire observability-pipeline-class** of silent fallback.
 
 ---
 
@@ -375,7 +392,7 @@ Add when ALL of the following hold:
 
 The class-name is what makes the lesson transferable, not multi-agent witness. A single-agent-confirmed instance with a concrete trace + identified defense pattern is sufficient for canonicalization (instances 4, 5, 7, 8 are all single-agent-confirmed). Cross-agent triangulation strengthens the framing but isn't a precondition.
 
-Add as a new numbered section (the next number is **12** — numbering is append-only; retired instances keep their slot, see Instance 10) with the same fields: Surface / Failure shape / Recurrence / Defense status. Increment the intro paragraph's active-instance count + the Defense-pattern emergence header's `N-of-M active instances` count too.
+Add as a new numbered section (the next number is **13** — numbering is append-only; retired instances keep their slot, see Instance 10) with the same fields: Surface / Failure shape / Recurrence / Defense status. Increment the intro paragraph's active-instance count + the Defense-pattern emergence header's `N-of-M active instances` count too.
 
 ---
 

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,230 @@
+#!/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 (first hit wins; may be empty) ─────────
+# 1. $MACF_EXPECTED_BOT_LOGIN — explicit operator/test override.
+# 2. .macf/macf-agent.json — derive `<name>[bot]` from the workspace config.
+#    The canonical workspace field is `agent_name`; the repo-side
+#    agent-config.json carries `app_name`. Accept either (agent_name first).
+# 3. empty — fall back to the type-based check below.
+EXPECTED_LOGIN="${MACF_EXPECTED_BOT_LOGIN:-}"
+if [[ -z "$EXPECTED_LOGIN" ]]; then
+  AGENT_JSON="${CLAUDE_PROJECT_DIR:-.}/.macf/macf-agent.json"
+  if [[ -f "$AGENT_JSON" ]]; then
+    AGENT_NAME="$(jq -r '.agent_name // .app_name // ""' "$AGENT_JSON" 2>/dev/null || echo "")"
+    if [[ -n "$AGENT_NAME" ]]; then
+      # Append `[bot]` exactly once (tolerate a config that already carries it).
+      EXPECTED_LOGIN="${AGENT_NAME%"[bot]"}[bot]"
+    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=1
+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).