@hasna/skills 0.1.60 → 0.1.62

package/agent-skills/inbox/scripts/inbox

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -u
+
+signature=${1:-${INBOX_SIGNATURE:-}}
+poll_seconds=${2:-${INBOX_MONITOR_POLL_SECONDS:-15}}
+state_dir=${INBOX_MONITOR_STATE_DIR:-state/monitors}
+max_polls=${INBOX_MONITOR_MAX_POLLS:-0}
+since_duration=${INBOX_MONITOR_SINCE_DURATION:-30m}
+page_limit=${INBOX_MONITOR_PAGE_LIMIT:-1000}
+
+if [[ -z "$signature" ]]; then
+  printf 'usage: %s <content-signature> [poll-seconds]\n' "$0" >&2
+  exit 2
+fi
+if [[ ! "$page_limit" =~ ^[1-9][0-9]*$ ]]; then
+  printf 'inbox: INBOX_MONITOR_PAGE_LIMIT must be a positive integer\n' >&2
+  exit 2
+fi
+
+mkdir -p "$state_dir"
+cursor_file="$state_dir/inbox.$$.cursor"
+self_identities_file="$state_dir/inbox.$$.self-identities"
+: >"$self_identities_file"
+
+messages() {
+  jq -c 'if type == "array" then . elif (.messages? | type) == "array" then .messages elif (.items? | type) == "array" then .items elif (.data? | type) == "array" then .data else error("unsupported conversations since response") end'
+}
+
+remember_identity() {
+  local identity=$1
+  [[ -z "$identity" ]] && return 0
+  grep -Fqx -- "$identity" "$self_identities_file" || printf '%s\n' "$identity" >>"$self_identities_file"
+}
+
+remember_current_identities() {
+  local current_json current_name presence_json registered_ids
+  current_json=$(conversations whoami --json 2>/dev/null) || return 1
+  current_name=$(printf '%s' "$current_json" | jq -r 'if type == "object" then .agent // empty else empty end') || return 1
+  [[ -z "$current_name" ]] && return 0
+  remember_identity "$current_name"
+
+  presence_json=$(conversations agents list --json 2>/dev/null) || return 0
+  registered_ids=$(printf '%s' "$presence_json" | jq -r --arg agent "$current_name" '
+    (if type == "array" then . elif (.agents? | type) == "array" then .agents else [] end)
+    | .[]
+    | select(((.agent // "") | ascii_downcase) == ($agent | ascii_downcase))
+    | .id // empty') || return 0
+  while IFS= read -r registered_id; do
+    remember_identity "$registered_id"
+  done <<<"$registered_ids"
+}
+
+latest_cursor() {
+  jq -r '[.[] | .id // .message_id // empty | tonumber?] | max // 0'
+}
+
+fetch_messages() {
+  conversations since "$since_duration" --limit "$page_limit" -j 2>/dev/null
+}
+
+emit_inbound() {
+  jq -c --arg signature "$signature" --argjson cursor "$1" --rawfile self_identities "$self_identities_file" '
+    ($self_identities | split("\n") | map(select(length > 0))) as $identities
+    | .[]
+    | select(((.id // .message_id // 0) | tonumber? // 0) > $cursor)
+    | select((((.from_agent // "") as $from | (($identities | index($from)) != null) and ((.content // .message // .body // "") | tostring | contains($signature))) | not))'
+}
+
+seed=$(fetch_messages) || { printf 'inbox: failed to seed conversations cursor\n' >&2; exit 1; }
+seed=$(printf '%s' "$seed" | messages) || { printf 'inbox: invalid seed response\n' >&2; exit 1; }
+printf '%s\n' "$(printf '%s' "$seed" | latest_cursor)" >"$cursor_file"
+remember_current_identities || true
+
+failures=0
+polls=0
+
+finish_poll() {
+  ((polls += 1))
+  if ((max_polls > 0 && polls >= max_polls)); then
+    exit 0
+  fi
+}
+
+while true; do
+  sleep "$poll_seconds"
+  remember_current_identities || true
+  cursor=$(<"$cursor_file")
+
+  if response=$(fetch_messages) \
+    && normalized=$(printf '%s' "$response" | messages) \
+    && next_cursor=$(printf '%s' "$normalized" | latest_cursor) \
+    && printf '%s' "$normalized" | emit_inbound "$cursor"; then
+    if ((failures >= 4)); then
+      printf 'inbox: recovered after %d consecutive poll failures\n' "$failures"
+    fi
+    failures=0
+    if ((next_cursor > cursor)); then
+      printf '%s\n' "$next_cursor" >"$cursor_file"
+    fi
+    finish_poll
+    continue
+  fi
+
+  ((failures += 1))
+  if ((failures == 4)); then
+    printf 'inbox: DEGRADED after 4 consecutive poll failures; inbox may be stale\n'
+  fi
+  finish_poll
+done

package/agent-skills/inbox/tests/test_registered_sender_id.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=$(cd "$(dirname "$0")/../../.." && pwd)
+candidate=${INBOX_UNDER_TEST:-$root/agent-skills/inbox/scripts/inbox}
+if [[ ! -f "$candidate" ]]; then
+  printf 'FAIL: inbox command not found: %s\n' "$candidate" >&2
+  exit 2
+fi
+
+temporary=$(mktemp -d)
+trap 'rm -rf "$temporary"' EXIT
+mkdir -p "$temporary/bin" "$temporary/mock" "$temporary/state"
+
+cat >"$temporary/bin/conversations" <<'MOCK'
+#!/usr/bin/env bash
+set -euo pipefail
+
+case "${1:-}" in
+  whoami)
+    if [[ "${2:-}" == '--json' ]]; then
+      printf '%s\n' '{"agent":"Herminia"}'
+    else
+      printf '%s\n' 'Herminia'
+    fi
+    ;;
+  agents)
+    [[ "${2:-}" == 'list' && "${3:-}" == '--json' ]]
+    printf '%s\n' '{"agents":[{"id":"b27c591d","agent":"herminia"}]}'
+    ;;
+  since)
+    [[ "${2:-}" == '30m' \
+      && "${3:-}" == '--limit' \
+      && "${4:-}" == '1000' \
+      && "${5:-}" == '-j' \
+      && "${6:-}" == '' ]]
+    calls_file="$MOCK_CONVERSATIONS_STATE/since.calls"
+    calls=0
+    [[ -f "$calls_file" ]] && calls=$(<"$calls_file")
+    calls=$((calls + 1))
+    printf '%s\n' "$calls" >"$calls_file"
+
+    if ((calls == 1)); then
+      printf '%s\n' '[{"id":200,"from_agent":"seed-agent","content":"seed","channel":"open-skills"}]'
+    elif ((calls == 2)); then
+      printf '%s\n' '[{"id":201,"from_agent":"b27c591d","content":"own signed post [inbox:test-seat]","channel":"open-skills"},{"id":202,"from_agent":"Herminia","content":"unsigned same-name peer traffic","channel":"open-skills"},{"id":203,"from_agent":"incident-agent","content":"incident traffic","channel":"incidents"},{"id":204,"from_agent":"project-agent","content":"project traffic","channel":"open-skills"}]'
+    else
+      printf '%s\n' '[]'
+    fi
+    ;;
+  *)
+    printf 'unexpected conversations command: %s\n' "$*" >&2
+    exit 64
+    ;;
+esac
+MOCK
+chmod +x "$temporary/bin/conversations"
+
+set +e
+output=$(PATH="$temporary/bin:$PATH" \
+  MOCK_CONVERSATIONS_STATE="$temporary/mock" \
+  INBOX_MONITOR_STATE_DIR="$temporary/state" \
+  INBOX_MONITOR_MAX_POLLS=1 \
+  bash "$candidate" '[inbox:test-seat]' 0 2>"$temporary/stderr")
+command_status=$?
+set -e
+
+if ((command_status != 0)); then
+  printf 'FAIL: inbox command exited %d before behavior could be checked\n' "$command_status" >&2
+  sed -n '1,20p' "$temporary/stderr" >&2
+  exit 2
+fi
+
+if ! actual_ids=$(printf '%s\n' "$output" | jq -r '.id'); then
+  printf '%s\n' 'FAIL: inbox command output was not newline-delimited message JSON' >&2
+  exit 2
+fi
+
+v120_ids=$'201\n202\n203\n204'
+expected_ids=$'202\n203\n204'
+if [[ "$actual_ids" == "$v120_ids" ]]; then
+  printf '%s\n' 'observed v1.2.0 visible IDs: 201,202,203,204' >&2
+fi
+
+if [[ "$actual_ids" != "$expected_ids" ]]; then
+  printf '%s\n' 'FAIL: signed own post stored under registered sender ID b27c591d remained visible' >&2
+  printf '%s\n' 'expected visible IDs: 202,203,204' >&2
+  printf 'actual visible IDs: %s\n' "${actual_ids//$'\n'/,}" >&2
+  exit 1
+fi
+
+printf '%s\n' 'PASS: own registered sender ID suppressed; same-name peer, incident, and project traffic visible'

package/agent-skills/inbox-monitor/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: inbox-monitor
+description: Arm a resilient interactive-session inbox monitor over the unified conversations feed, with per-session cursors, rotating-identity-safe self filtering, and degraded-monitor reporting.
+user_invocable: true
+---
+
+# inbox-monitor — Interactive Session Inbox Monitor
+
+Arm this monitor at the start of every interactive session after login. It surfaces new channel messages, DMs, and blockers through one `conversations since` feed without replaying messages already present when the monitor starts.
+
+## Arm the monitor
+
+Choose an opaque signature unique to this seat and session. Include it in **every** channel message, DM, and blocker the session writes. Do not reuse a signature across concurrently active seats.
+
+```bash
+INBOX_SIGNATURE="[inbox:$(hostname):$$:$(date +%s)]"
+mkdir -p state/monitors
+nohup bash ~/.claude/skills/inbox-monitor/scripts/inbox_monitor.sh \
+  "$INBOX_SIGNATURE" >state/monitors/inbox.log 2>&1 &
+echo $! >state/monitors/inbox.pid
+```
+
+Use the corresponding installed skill path for non-Claude agents. Keep `INBOX_SIGNATURE` in session context and append it verbatim to everything this session sends through `conversations`.
+
+## Self-filter contract
+
+The monitor refreshes `conversations whoami` on every poll and persists the union of every non-empty name observed during that monitor process. A message is self-noise only when both conditions hold:
+
+1. `from_agent` is in that persisted union.
+2. Its textual content contains this seat's exact `INBOX_SIGNATURE`.
+
+Both checks are required. The identity file is machine-level and can rotate mid-session, while a name observed on this machine can also belong to a real message from another seat. Never replace the conjunction with a single-name comparison or a name-only exclusion.
+
+## Runtime guarantees
+
+- Uses one `conversations since <duration> --limit <n> -j` call per poll for channels, DMs, and blockers.
+- Keys max-message-id cursor and self-name state by monitor PID so concurrent sessions do not share progress.
+- Seeds the cursor at arm time and emits only later messages.
+- Emits a degraded-monitor warning after four consecutive failed polls and a recovery notice after the next successful poll.
+
+Treat a degraded warning as inbox uncertainty, not a quiet inbox. Check `conversations context` manually and repair or restart the monitor.

package/agent-skills/inbox-monitor/scripts/inbox_monitor.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -u
+
+signature=${1:-${INBOX_SIGNATURE:-}}
+poll_seconds=${2:-${INBOX_MONITOR_POLL_SECONDS:-15}}
+state_dir=${INBOX_MONITOR_STATE_DIR:-state/monitors}
+max_polls=${INBOX_MONITOR_MAX_POLLS:-0}
+since_duration=${INBOX_MONITOR_SINCE_DURATION:-30m}
+page_limit=${INBOX_MONITOR_PAGE_LIMIT:-1000}
+
+if [[ -z "$signature" ]]; then
+  printf 'usage: %s <content-signature> [poll-seconds]\n' "$0" >&2
+  exit 2
+fi
+if [[ ! "$page_limit" =~ ^[1-9][0-9]*$ ]]; then
+  printf 'inbox-monitor: INBOX_MONITOR_PAGE_LIMIT must be a positive integer\n' >&2
+  exit 2
+fi
+
+mkdir -p "$state_dir"
+cursor_file="$state_dir/inbox.$$.cursor"
+self_names_file="$state_dir/inbox.$$.self-names"
+: >"$self_names_file"
+
+messages() {
+  jq -c 'if type == "array" then . elif (.messages? | type) == "array" then .messages elif (.items? | type) == "array" then .items elif (.data? | type) == "array" then .data else error("unsupported conversations since response") end'
+}
+
+remember_current_name() {
+  local current_name
+  current_name=$(conversations whoami 2>/dev/null | head -n 1 | tr -d '\r') || return 1
+  [[ -z "$current_name" ]] && return 0
+  grep -Fqx -- "$current_name" "$self_names_file" || printf '%s\n' "$current_name" >>"$self_names_file"
+}
+
+latest_cursor() {
+  jq -r '[.[] | .id // .message_id // empty | tonumber?] | max // 0'
+}
+
+fetch_messages() {
+  conversations since "$since_duration" --limit "$page_limit" -j 2>/dev/null
+}
+
+emit_inbound() {
+  jq -c --arg signature "$signature" --argjson cursor "$1" --rawfile self_names "$self_names_file" '
+    ($self_names | split("\n") | map(select(length > 0))) as $names
+    | .[]
+    | select(((.id // .message_id // 0) | tonumber? // 0) > $cursor)
+    | select((((.from_agent // "") as $from | (($names | index($from)) != null) and ((.content // .message // .body // "") | tostring | contains($signature))) | not))'
+}
+
+seed=$(fetch_messages) || { printf 'inbox-monitor: failed to seed conversations cursor\n' >&2; exit 1; }
+seed=$(printf '%s' "$seed" | messages) || { printf 'inbox-monitor: invalid seed response\n' >&2; exit 1; }
+printf '%s\n' "$(printf '%s' "$seed" | latest_cursor)" >"$cursor_file"
+remember_current_name || true
+
+failures=0
+polls=0
+
+finish_poll() {
+  ((polls += 1))
+  if (( max_polls > 0 && polls >= max_polls )); then
+    exit 0
+  fi
+}
+while true; do
+  sleep "$poll_seconds"
+  remember_current_name || true
+  cursor=$(cat "$cursor_file")
+
+  if response=$(fetch_messages) \
+    && normalized=$(printf '%s' "$response" | messages) \
+    && next_cursor=$(printf '%s' "$normalized" | latest_cursor) \
+    && printf '%s' "$normalized" | emit_inbound "$cursor"; then
+    if (( failures >= 4 )); then
+      printf 'inbox-monitor: recovered after %d consecutive poll failures\n' "$failures"
+    fi
+    failures=0
+    if (( next_cursor > cursor )); then
+      printf '%s\n' "$next_cursor" >"$cursor_file"
+    fi
+    finish_poll
+    continue
+  fi
+
+  ((failures += 1))
+  if (( failures == 4 )); then
+    printf 'inbox-monitor: DEGRADED after 4 consecutive poll failures; inbox may be stale\n'
+  fi
+  finish_poll
+done

package/agent-skills/inbox-monitor/scripts/test_inbox_monitor.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root=$(cd "$(dirname "$0")/../../.." && pwd)
+temporary=$(mktemp -d)
+trap 'rm -rf "$temporary"' EXIT
+mkdir -p "$temporary/bin" "$temporary/state"
+
+cat >"$temporary/bin/conversations" <<'MOCK'
+#!/usr/bin/env bash
+set -euo pipefail
+
+counter_file="$MOCK_STATE/${1}.calls"
+count=0
+[[ -f "$counter_file" ]] && count=$(cat "$counter_file")
+count=$((count + 1))
+printf '%s\n' "$count" >"$counter_file"
+
+expect_since() {
+  [[ "${1:-}" == 'since' \
+    && "${2:-}" == '30m' \
+    && "${3:-}" == '--limit' \
+    && "${4:-}" == '1000' \
+    && "${5:-}" == '-j' \
+    && "${6:-}" == '' ]]
+}
+
+case "$1:$count" in
+  whoami:1) printf 'manius\n' ;;
+  whoami:2) printf 'fabricius\n' ;;
+  whoami:3) printf 'agent-ceo\n' ;;
+  since:1)
+    expect_since "$@"
+    printf '[{"id":100,"from_agent":"old","content":"seed"}]\n'
+    ;;
+  since:2)
+    expect_since "$@"
+    printf '%s\n' '[{"id":101,"from_agent":"fabricius","content":"own [seat-signature]"},{"id":102,"from_agent":"agent-ceo","content":"genuine before observation"}]'
+    ;;
+  since:3)
+    expect_since "$@"
+    printf '%s\n' '[{"id":103,"from_agent":"manius","content":"own after rotation [seat-signature]"},{"id":104,"from_agent":"agent-ceo","content":"own current [seat-signature]"},{"id":105,"from_agent":"agent-ceo","content":"genuine from same-name seat"}]'
+    ;;
+  *) exit 1 ;;
+esac
+MOCK
+chmod +x "$temporary/bin/conversations"
+
+output=$(PATH="$temporary/bin:$PATH" \
+  MOCK_STATE="$temporary" \
+  INBOX_MONITOR_STATE_DIR="$temporary/state" \
+  INBOX_MONITOR_MAX_POLLS=2 \
+  bash "$root/agent-skills/inbox-monitor/scripts/inbox_monitor.sh" '[seat-signature]' 0)
+
+actual_ids=$(printf '%s\n' "$output" | jq -r '.id')
+[[ "$actual_ids" == $'102\n105' ]]
+! printf '%s\n' "$output" | jq -e 'select(.id == 101 or .id == 103 or .id == 104)' >/dev/null
+
+names_file=$(find "$temporary/state" -name 'inbox.*.self-names' -type f)
+[[ $(sort "$names_file") == $'agent-ceo\nfabricius\nmanius' ]]
+cursor_file=$(find "$temporary/state" -name 'inbox.*.cursor' -type f)
+[[ $(cat "$cursor_file") == 105 ]]
+
+fixture='[{"id":101,"from_agent":"fabricius","content":"own [seat-signature]"},{"id":105,"from_agent":"agent-ceo","content":"genuine from same-name seat"}]'
+[[ $(printf '%s' "$fixture" | jq --arg me manius '[.[] | select(.from_agent != $me) | .id]') == '[
+  101,
+  105
+]' ]]
+[[ $(printf '%s' "$fixture" | jq --arg me agent-ceo '[.[] | select(.from_agent != $me) | .id]') == '[
+  101
+]' ]]

package/agent-skills/merge-pr/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: merge-pr
+description: Merge a GitHub pull request, merge when green, use a merge queue, or decide whether a pull request is mergeable. Use only for explicit merge intent, not ordinary review.
+---
+
+# Merge PR
+
+Keep merge authority tied to fresh exact-head evidence. Read
+[merge-safety.md](references/merge-safety.md) before an actual merge.
+
+## Modes
+
+- `preflight`: read-only advice; never fetch, checkout, push, comment, label,
+  approve, close, enqueue, or merge.
+- `immediate-merge`: merge now after every gate passes.
+- `auto-merge`: use only when the user explicitly requested delayed merge.
+- `merge-queue`: follow the repository queue; it is not a merge strategy.
+
+## Required contract
+
+For an actual merge:
+
+1. Reuse the owning native goal/plan and exact Todo. Freeze one nonblank
+   `acceptance_scope`; record the cumulative repair-cycle count.
+2. Declare `routine` or `elevated`. Unknown is elevated and cannot authorize a
+   merge. Routine requires one independent exact-head artifact and permits one
+   repair cycle; elevated requires two and permits two. A head change
+   invalidates artifacts without resetting the cap.
+3. Keep worker, reviewers, and executor distinct. Every artifact must name the
+   repository, PR, exact head SHA, frozen scope, reviewer identity or run ID,
+   timestamp, verdict, checked risks, and blocking findings.
+4. Immediately before execution, re-read the PR, exact head, checks, reviews,
+   draft/conflict state, base/protection policy, and queue behavior. Do not use
+   stale preflight as merge authority.
+5. Generate the command with
+   `scripts/merge_pr_guard.py build --preflight <fresh.json>
+   --task-id <todo-id> --acceptance-scope <frozen-scope>
+   --repair-cycle-count <cumulative-count> ...`. Never hand compose a squash
+   command.
+6. Execute the returned argv exactly once. It always includes
+   `--match-head-commit`; it never includes admin, force, direct-main push, or
+   branch deletion. Use auto mode only with explicit delayed intent.
+7. Run `scripts/merge_pr_guard.py postverify` against the provider result and
+   save its required receipt. For auto or queue mode, wait until the provider
+   reports `MERGED`; enablement or enqueue is not merge completion. Do not
+   report clean until postverify exits zero.
+
+## Squash message rule
+
+Every squash command must carry an explicit one-line subject and explicit body.
+An omitted body becomes the empty string. Custom bodies retain their text after
+line-ending normalization. Subject or body input containing a
+`Co-Authored-By` trailer, with any case or whitespace variation, fails before
+merge; never strip and continue.
+
+```bash
+python3 agent-skills/merge-pr/scripts/merge_pr_guard.py build \
+  --preflight /path/to/fresh-preflight.json \
+  --task-id "00000000-0000-4000-8000-000000000000" \
+  --acceptance-scope "task-owned-frozen-scope" \
+  --repair-cycle-count 0 \
+  --strategy squash \
+  --subject "fix: preserve merge provenance" \
+  --body ""
+```
+
+This guard authorizes explicit squash merges and policy-owned merge queues.
+Merge and rebase strategies need a different guard that verifies every
+resulting commit, so this workflow rejects them.
+
+## Postverify
+
+Postverify must query the actual provider merge commit, not source commits or a
+locally predicted message. It writes a durable `clean` or `failed` receipt,
+including message digest and forbidden-trailer line numbers without echoing the
+message. Here `clean` means trailer-clean, not byte-for-byte equality with the
+requested message. A synthesized trailer is a failed result. Fixture mode is
+test-only, marks receipts non-authoritative, and can never complete a live
+merge. Pass the build result's task, mode, scope, cycle count, base, exact head,
+preflight digest, and command-argv digest to postverify. Postverify must also
+read the exact preflight and saved command-plan JSON; it recomputes both digests
+and rejects any field, message, or argv mismatch before querying the provider.
+
+Never rewrite protected-main history, revert, force push, or delete the branch
+in response. Record the failure and escalate through the owning task.

package/agent-skills/merge-pr/references/merge-safety.md

@@ -0,0 +1,82 @@
+# Merge safety contract
+
+## Read-only preflight
+
+Capture a fresh JSON snapshot with:
+
+- mode, repository, PR, URL, base, head, and exact head SHA;
+- explicit risk tier and frozen acceptance scope;
+- cumulative repair-cycle count and cap;
+- checks, reviews, draft/conflict/merge state, and branch/queue policy;
+- exactly the tier-required independent reviewer artifacts;
+- worker and executor identities;
+- blocking reasons, warnings, verdict, and observation time.
+
+Preflight may use read-only `gh pr view`, `gh pr checks`, and repository-rule
+queries. It must not mutate local git or GitHub. `mergeable` is advisory until
+the executor repeats the checks immediately before merge.
+
+## Bounded review
+
+- Routine: one exact-head artifact and at most one cumulative repair/re-review
+  cycle.
+- Elevated: two independent exact-head artifacts and at most two cumulative
+  cycles.
+- Worker and executor cannot review. Reviewer identities and run IDs must be
+  distinct.
+- Every artifact must match repository, PR, exact head, and frozen scope. A
+  stale, future, malformed, blocking, duplicate, worker-authored,
+  executor-authored, or scope-mismatched artifact blocks.
+- A head change invalidates artifacts but never resets the repair-cycle count.
+- At the cap, land only if frozen acceptance passes; otherwise simplify, split,
+  close, or defer. Do not add another review layer.
+
+## Command construction
+
+Use the guard's argv output. For squash it always supplies `--subject`,
+`--body`, and `--match-head-commit`. The guard rejects a
+`Co-Authored-By` trailer rather than deleting it. It has no interface for
+`--admin`, force, direct pushes, or branch deletion. Auto mode additionally
+requires the explicit `--delayed-intent` acknowledgement. The executor must
+pass the Todo ID, task-owned frozen scope, and cumulative repair-cycle count
+separately; all must match the fresh snapshot. This guard permits squash and
+policy-owned queues only. It rejects merge and rebase strategies because their
+multi-commit results require a wider provenance check.
+
+## Provider postverify
+
+After provider mutation:
+
+For auto and queue modes, start these checks only after the provider reports
+`MERGED`; an enabled or queued PR is still pending.
+
+1. Recompute the preflight and complete command-argv digests, then match the
+   saved command plan.
+2. Re-read the PR and require `MERGED`.
+3. Match the provider-reported source head to the reviewed head.
+4. Resolve the provider merge-commit SHA.
+5. Fetch that commit's actual message.
+6. Scan it for forbidden trailers.
+7. Bind the receipt to the task, mode, scope, cycle count, preflight digest,
+   provider URL, base, source head, and merge commit.
+8. Persist the receipt before interpreting success.
+
+A forbidden trailer or provider mismatch produces a durable failed receipt and
+nonzero exit. Do not claim a clean merge, rewrite protected main, revert, force
+push, or delete the branch. Postverify is evidence-only and cannot reopen the
+review budget.
+
+`clean` is scoped to the forbidden-trailer policy; it is not a byte-for-byte
+message assertion. `--fixture` exists only for inert tests. Fixture receipts
+name their source, set `authoritative: false`, bind their target to the supplied
+repository and PR, and cannot satisfy live postverify.
+
+## Recovery and workflow rollback
+
+On failed postverify, preserve the failed receipt, mark the owning Todo blocked,
+and report the provider mismatch through the normal incident or blocker
+surface. Do not retry the same mutation or automate a protected-history revert.
+Correct product behavior, if needed, through a new reviewed PR that preserves
+history. Before further merges, roll back a faulty workflow version through an
+ordinary PR that reverts the skill change, then repeat the full exact-head
+review and release gates.