feat(process): #303 H6 merge-consent derived from ## Done-when checklist

Wave 2 hook H6: derive merge-consent from state instead of memory. An
issue's ## Done-when checklist (issue body) becomes the machine-readable
source of truth for whether its PR may merge — the structural fix for the
queue-drift #303 tracks (status was living in append-only prose).

- pretooluse-merge-consent.sh (Claude PreToolUse on mcp__gitea__
  pull_request_write): a merge is ALLOWED only when the PR's CI is green
  AND every ## Done-when box on the linked issue (fixes #N) is ticked;
  DENY on an unticked box / red CI; ASK (human prompt) when state isn't
  derivable (no linked issue, no section, no creds, Gitea down). Docs/
  process-only PRs exempt.
- .husky/pre-push -> prepush-donewhen.sh: fail-open backstop for a direct
  `git push origin main`; blocks only on a positively-proven unticked box.

Gitea auth from env only (ETV_GITEA_BASICAUTH / ETV_GITEA_TOKEN,
ETV_GITEA_URL) — nothing committed; without creds the gate degrades to
today's manual confirmation, never a silent pass. Non-breaking rollout:
until issues adopt ## Done-when the merge hook simply asks.

Pipe-tested: non-merge->allow, no-creds->ask, docs-only->allow, checklist
parser (unit), linked-issue extraction, and a live end-to-end block path
(temp Done-when on #303 -> exit 1 -> restored). Docs: CLAUDE.md Task
Completion Protocol + decisions.md entry. Refs #303.

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

.claude/hooks/prepush-donewhen.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Husky pre-push backstop for ersatztv#303 H6 — the fast-forward-to-main path the Claude merge
+# hook (pretooluse-merge-consent.sh) can't see. Reads git's pre-push ref lines on stdin; for a push
+# to main it scans the pushed commits for a Gitea close-keyword (`fixes #N`), and if the linked
+# issue's "## Done-when" checklist still has unticked boxes it BLOCKS the push.
+#
+# A git hook has no interactive "ask", so this is deliberately fail-OPEN: it only blocks when it can
+# positively prove an unticked box (creds present, issue fetched, non-docs change). No creds, Gitea
+# unreachable, docs-only diff, or no linked issue -> allow (a loud warning at most). The authoritative
+# gate is the merge hook; this just catches a direct `git push origin main`.
+#
+# Auth (never committed): ETV_GITEA_TOKEN or ETV_GITEA_BASICAUTH; ETV_GITEA_URL overrides the base.
+set -euo pipefail
+
+# git passes "<localref> <localsha> <remoteref> <remotesha>" lines on stdin.
+refs=$(cat || true)
+printf '%s\n' "$refs" | grep -q 'refs/heads/main' || exit 0   # only gate pushes to main
+
+base_url="${ETV_GITEA_URL:-http://192.168.1.95:3000}/api/v1"
+if [ -z "${ETV_GITEA_TOKEN:-}" ] && [ -z "${ETV_GITEA_BASICAUTH:-}" ]; then
+  exit 0   # can't verify -> fail-open (the merge hook is the real gate)
+fi
+gq() {
+  if [ -n "${ETV_GITEA_TOKEN:-}" ]; then
+    curl -sf -H "Authorization: token $ETV_GITEA_TOKEN" "$base_url/$1" 2>/dev/null || true
+  else
+    curl -sf -u "$ETV_GITEA_BASICAUTH" "$base_url/$1" 2>/dev/null || true
+  fi
+}
+
+zero=0000000000000000000000000000000000000000
+blocked=""
+while read -r localref localsha remoteref remotesha; do
+  [ "$remoteref" = "refs/heads/main" ] || continue
+  [ "$localsha" = "$zero" ] && continue   # branch deletion
+  # Commit range being pushed. New branch (remotesha all-zero) -> just the tip, don't rescan history.
+  if [ "$remotesha" = "$zero" ]; then range="$localsha -1"; else range="$remotesha..$localsha"; fi
+  msgs=$(git log --format='%B' $range 2>/dev/null || true)
+  issues=$(printf '%s' "$msgs" | grep -ioE '(close[sd]?|fix(e[sd])?|resolve[sd]?) +#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+  [ -n "$issues" ] || continue
+
+  # Docs-only exemption over the pushed range.
+  changed=$(git diff --name-only $range 2>/dev/null || true)
+  if [ -n "$changed" ] && ! printf '%s\n' "$changed" | grep -qvE '^(docs/|\.claude/|\.husky/|\.gitea/|.*\.md$)'; then
+    continue
+  fi
+
+  for n in $issues; do
+    ibody=$(gq "repos/timothy/ersatztv/issues/$n" | jq -r '.body // ""' 2>/dev/null || true)
+    [ -n "$ibody" ] || continue   # can't fetch -> fail-open
+    unchecked=$(printf '%s\n' "$ibody" | awk '
+      /^##[[:space:]]+[Dd]one-when/ {grab=1; next}
+      grab && /^##[[:space:]]/ {grab=0}
+      grab {print}' | grep -cE '^[[:space:]]*[-*][[:space:]]+\[[[:space:]]\]' || true)
+    if [ "${unchecked:-0}" -gt 0 ]; then
+      blocked="${blocked}  - issue #$n has $unchecked unticked ## Done-when box(es)\n"
+    fi
+  done
+done <<EOF
+$refs
+EOF
+
+if [ -n "$blocked" ]; then
+  printf 'husky - H6 merge-consent (ersatztv#303): push to main BLOCKED\n' >&2
+  printf '%b' "$blocked" >&2
+  printf 'Finish/tick every Done-when criterion (incl. adversarial review) first, or push a docs-only change.\n' >&2
+  exit 1
+fi
+exit 0

.claude/hooks/pretooluse-merge-consent.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# PreToolUse / mcp__gitea__pull_request_write — derive merge consent from STATE instead of
+# trusting the agent's judgment (ersatztv#303 H6). A PR merge is the one irreversible op; allow it
+# only when BOTH are true:
+#   (a) the PR's CI combined status is green, AND
+#   (b) every checkbox in the linked issue's "## Done-when" section is ticked.
+# The "## Done-when" issue-body checklist is the convention (docs/decisions.md, CLAUDE.md Task
+# Completion Protocol). One box is "adversarial review passed"; the others are per-issue.
+#
+# Decision policy — a CONSENT gate, so it does NOT fail silently open:
+#   - state derivable and NOT satisfied            -> deny  (actionable reason)
+#   - state derivable and satisfied                -> allow
+#   - state NOT derivable (no creds, Gitea down,
+#     no linked issue, no Done-when section)       -> ask   (surface to a human/session judgment)
+# Only a real merge is gated; every other pull_request_write method is allowed untouched.
+#
+# Gitea auth from env (never committed): ETV_GITEA_TOKEN (a token) OR ETV_GITEA_BASICAUTH (user:pass).
+# ETV_GITEA_URL overrides the base (default: the LAN instance; a LAN address, not a secret).
+set -euo pipefail
+input=$(cat)
+
+decide() { # $1=allow|deny|ask  $2=reason
+  case "$1" in
+    allow) exit 0 ;;
+    deny)  jq -n --arg r "$2" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}'; exit 0 ;;
+    ask)   jq -n --arg r "$2" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"ask",permissionDecisionReason:$r}}'; exit 0 ;;
+  esac
+}
+
+method=$(printf '%s' "$input" | jq -r '.tool_input.method // ""' 2>/dev/null || true)
+[ "$method" = "merge" ] || decide allow ""
+
+owner=$(printf '%s' "$input" | jq -r '.tool_input.owner // ""' 2>/dev/null || true)
+repo=$(printf '%s'  "$input" | jq -r '.tool_input.repo  // ""' 2>/dev/null || true)
+pr=$(printf '%s'    "$input" | jq -r '.tool_input.pull_number // ""' 2>/dev/null || true)
+mwcs=$(printf '%s'  "$input" | jq -r '.tool_input.merge_when_checks_succeed // false' 2>/dev/null || true)
+[ -n "$owner" ] && [ -n "$repo" ] && [ -n "$pr" ] || decide ask "H6 merge gate: could not read owner/repo/pull_number from the merge call; confirm manually that CI is green and the issue's Done-when boxes are ticked."
+
+base_url="${ETV_GITEA_URL:-http://192.168.1.95:3000}/api/v1"
+# curl wrapper carrying whichever auth is configured; empty output on any failure.
+gq() {
+  local path="$1"
+  if [ -n "${ETV_GITEA_TOKEN:-}" ]; then
+    curl -sf -H "Authorization: token $ETV_GITEA_TOKEN" "$base_url/$path" 2>/dev/null || true
+  elif [ -n "${ETV_GITEA_BASICAUTH:-}" ]; then
+    curl -sf -u "$ETV_GITEA_BASICAUTH" "$base_url/$path" 2>/dev/null || true
+  else
+    return 1
+  fi
+}
+if [ -z "${ETV_GITEA_TOKEN:-}" ] && [ -z "${ETV_GITEA_BASICAUTH:-}" ]; then
+  decide ask "H6 merge gate: no Gitea credentials in env (ETV_GITEA_TOKEN or ETV_GITEA_BASICAUTH), so CI/Done-when state can't be verified. Confirm manually that CI is green and the linked issue's Done-when boxes are all ticked, then approve."
+fi
+
+prjson=$(gq "repos/$owner/$repo/pulls/$pr")
+[ -n "$prjson" ] || decide ask "H6 merge gate: could not fetch PR #$pr from Gitea (unreachable or auth rejected). Verify CI-green + Done-when manually before merging."
+
+sha=$(printf '%s' "$prjson" | jq -r '.head.sha // ""' 2>/dev/null || true)
+body=$(printf '%s' "$prjson" | jq -r '.body // ""' 2>/dev/null || true)
+
+# --- Docs-only exemption: if every changed file is docs/process, skip the gate. ---
+files=$(gq "repos/$owner/$repo/pulls/$pr/files?limit=100" | jq -r '.[].filename // empty' 2>/dev/null || true)
+if [ -n "$files" ] && ! printf '%s\n' "$files" | grep -qvE '^(docs/|\.claude/|\.husky/|\.gitea/|.*\.md$)'; then
+  decide allow ""   # all changed files are docs/process-only
+fi
+
+# --- Linked issue: Gitea auto-close keywords in the PR body. ---
+issues=$(printf '%s' "$body" | grep -ioE '(close[sd]?|fix(e[sd])?|resolve[sd]?) +#[0-9]+' | grep -oE '[0-9]+' | sort -u || true)
+[ -n "$issues" ] || decide ask "H6 merge gate: PR #$pr has no linked issue (no 'fixes #N' / 'closes #N' in its body), so there is no Done-when checklist to derive consent from. Confirm the work is complete + reviewed, then approve."
+
+# --- (b) Done-when checkboxes: every linked issue must have an all-ticked section. ---
+for n in $issues; do
+  ibody=$(gq "repos/$owner/$repo/issues/$n" | jq -r '.body // ""' 2>/dev/null || true)
+  [ -n "$ibody" ] || decide ask "H6 merge gate: could not fetch linked issue #$n. Verify its Done-when checklist manually before merging."
+  # Slice the "## Done-when" section: from that header to the next "## " (or EOF).
+  section=$(printf '%s\n' "$ibody" | awk '
+    /^##[[:space:]]+[Dd]one-when/ {grab=1; next}
+    grab && /^##[[:space:]]/ {grab=0}
+    grab {print}')
+  if [ -z "$(printf '%s' "$section" | tr -d '[:space:]')" ]; then
+    decide ask "H6 merge gate: linked issue #$n has no '## Done-when' checklist section (the merge-consent convention — see CLAUDE.md Task Completion Protocol). Add one, or confirm completion manually and approve."
+  fi
+  unchecked=$(printf '%s\n' "$section" | grep -cE '^[[:space:]]*[-*][[:space:]]+\[[[:space:]]\]' || true)
+  if [ "${unchecked:-0}" -gt 0 ]; then
+    decide deny "H6 merge gate: BLOCKED — linked issue #$n has $unchecked unticked box(es) in its ## Done-when checklist. Finish (or explicitly tick) every completion criterion — including the adversarial-review box — before merging PR #$pr."
+  fi
+done
+
+# --- (a) CI combined status must be green (unless deferring to Gitea's own check-gate). ---
+if [ "$mwcs" != "true" ]; then
+  [ -n "$sha" ] || decide ask "H6 merge gate: could not resolve PR #$pr head sha to check CI. Verify CI is green before merging."
+  state=$(gq "repos/$owner/$repo/commits/$sha/status" | jq -r '.state // ""' 2>/dev/null || true)
+  case "$state" in
+    success) : ;;
+    "")      decide ask "H6 merge gate: could not read CI status for PR #$pr ($sha). Verify CI is green before merging." ;;
+    *)       decide deny "H6 merge gate: BLOCKED — PR #$pr CI status is '$state', not 'success'. Wait for a green build (or pass merge_when_checks_succeed to let Gitea gate it) before merging." ;;
+  esac
+fi
+
+# Both derivable and satisfied -> allow.
+decide allow ""

.claude/settings.json

@@ -36,6 +36,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "mcp__gitea__pull_request_write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/pretooluse-merge-consent.sh\"",
+            "timeout": 15
+          }
+        ]
       }
     ],
     "PostToolUse": [