e3d-pilot 0.0.0-stage → 0.1.0

package/bin/e3d-backend-benchmark

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=lib/providers/common.sh
+source "$REPO_ROOT/lib/providers/common.sh"
+E3D_BENCHMARK_TIMEOUT="${E3D_BENCHMARK_TIMEOUT:-1800}"
+
+usage() {
+  cat <<'EOF'
+Usage: e3d-backend-benchmark --repo <path> --task-id <id> --prompt <file>
+       [--backends codex,claude,grok-build] [--verify <command>] [--output <json>]
+
+Runs the identical prompt in a detached temporary worktree per backend. It
+never commits, pushes, publishes, or merges. Missing token/cost fields are null.
+EOF
+}
+
+die() { printf 'error: %s\n' "$*" >&2; exit 1; }
+
+repo="" task_id="" prompt_file="" backends="codex,claude,grok-build" verify_command="" output_file=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo) repo="${2:-}"; shift 2 ;;
+    --task-id) task_id="${2:-}"; shift 2 ;;
+    --prompt) prompt_file="${2:-}"; shift 2 ;;
+    --backends) backends="${2:-}"; shift 2 ;;
+    --verify) verify_command="${2:-}"; shift 2 ;;
+    --output) output_file="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[[ -n "$repo" && -n "$task_id" && -n "$prompt_file" ]] || { usage >&2; exit 1; }
+[[ -d "$repo" ]] || die "repository not found: $repo"
+repo="$(cd "$repo" && pwd -P)"
+[[ -f "$prompt_file" ]] || die "prompt file not found: $prompt_file"
+prompt_file="$(cd "$(dirname "$prompt_file")" && pwd -P)/$(basename "$prompt_file")"
+git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 || die "not a git repository: $repo"
+command -v jq >/dev/null 2>&1 || die "jq is required"
+[[ "$E3D_BENCHMARK_TIMEOUT" =~ ^[0-9]+$ ]] && (( E3D_BENCHMARK_TIMEOUT > 0 )) \
+  || die "E3D_BENCHMARK_TIMEOUT must be a positive integer"
+
+[[ -n "$output_file" ]] || output_file="$repo/.e3d-pilot/benchmarks/${task_id}.json"
+mkdir -p "$(dirname "$output_file")"
+artifact_dir="${output_file%.json}.artifacts"
+mkdir -p "$artifact_dir"
+results_file="$(mktemp "${TMPDIR:-/tmp}/e3d-benchmark-results.XXXXXX")"
+worktrees_file="$(mktemp "${TMPDIR:-/tmp}/e3d-benchmark-worktrees.XXXXXX")"
+
+cleanup() {
+  local path
+  while IFS= read -r path; do
+    [[ -n "$path" && -d "$path" ]] || continue
+    git -C "$repo" worktree remove --force "$path" >/dev/null 2>&1 || true
+  done < "$worktrees_file"
+  rm -f "$results_file" "$worktrees_file"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM HUP
+
+IFS=',' read -r -a backend_list <<< "$backends"
+for backend in "${backend_list[@]}"; do
+  case "$backend" in codex|claude|grok-build) ;; *) die "unsupported benchmark backend: $backend" ;; esac
+  provider="$REPO_ROOT/lib/providers/$backend"
+  [[ -x "$provider" ]] || die "provider adapter missing or not executable: $provider"
+
+  worktree="$(mktemp -d "${TMPDIR:-/tmp}/e3d-benchmark.${backend}.XXXXXX")"
+  # git worktree add requires the destination not to exist.
+  rmdir "$worktree"
+  git -C "$repo" worktree add --detach "$worktree" HEAD >/dev/null
+  printf '%s\n' "$worktree" >> "$worktrees_file"
+  stdout_file="$artifact_dir/${backend}.stdout"
+  stderr_file="$artifact_dir/${backend}.stderr"
+  verify_stdout_file="$artifact_dir/${backend}.verify.stdout"
+  verify_stderr_file="$artifact_dir/${backend}.verify.stderr"
+
+  start_seconds="$(date +%s)"
+  set +e
+  (cd "$worktree" && provider_run_with_timeout "$E3D_BENCHMARK_TIMEOUT" env \
+    E3D_PILOT_PROVIDER_MODE=execute GROK_BUILD_OUTPUT_FORMAT=json \
+    "$provider" "$prompt_file") >"$stdout_file" 2>"$stderr_file"
+  backend_status=$?
+  set -e
+  end_seconds="$(date +%s)"
+
+  additions=0 deletions=0 files_changed=0
+  while IFS=$'\t' read -r add del path; do
+    [[ -n "$path" ]] || continue
+    files_changed=$((files_changed + 1))
+    [[ "$add" == "-" ]] || additions=$((additions + add))
+    [[ "$del" == "-" ]] || deletions=$((deletions + del))
+  done < <(git -C "$worktree" diff --numstat --no-renames -- .)
+  while IFS= read -r path; do
+    [[ -n "$path" ]] || continue
+    files_changed=$((files_changed + 1))
+    [[ -f "$worktree/$path" ]] && additions=$((additions + $(wc -l < "$worktree/$path")))
+  done < <(git -C "$worktree" ls-files --others --exclude-standard)
+
+  verify_status_json=null
+  verify_exit_json=null
+  if [[ -n "$verify_command" ]]; then
+    set +e
+    (cd "$worktree" && bash -lc "$verify_command") >"$verify_stdout_file" 2>"$verify_stderr_file"
+    verify_status=$?
+    set -e
+    verify_exit_json="$verify_status"
+    if [[ $verify_status -eq 0 ]]; then verify_status_json=true; else verify_status_json=false; fi
+  fi
+
+  tokens_json=null cost_json=null model_json=null usage_partial_json=null
+  if [[ "$backend" == "grok-build" ]] && jq -e 'type == "object"' "$stdout_file" >/dev/null 2>&1; then
+    tokens_json="$(jq -c '.usage.total_tokens // .usage.totalTokens // .total_tokens // null' "$stdout_file")"
+    cost_json="$(jq -c '.total_cost_usd // .usage.total_cost_usd // null' "$stdout_file")"
+    model_json="$(jq -c '.model // ((.usage.models? // {}) | keys[0]?) // null' "$stdout_file")"
+    usage_partial_json="$(jq -c '.cost_is_partial // .usage_is_incomplete // null' "$stdout_file")"
+  fi
+
+  success_json=false
+  if [[ $backend_status -eq 0 && "$verify_status_json" != "false" ]]; then success_json=true; fi
+  stderr_text="$(tail -c 8000 "$stderr_file" 2>/dev/null || true)"
+  jq -n \
+    --arg backend "$backend" --arg task_id "$task_id" --argjson duration "$((end_seconds - start_seconds))" \
+    --argjson success "$success_json" --argjson exit_status "$backend_status" \
+    --argjson files_changed "$files_changed" --argjson lines_added "$additions" --argjson lines_removed "$deletions" \
+    --argjson tests_passed "$verify_status_json" --argjson test_exit_status "$verify_exit_json" \
+    --argjson tokens "$tokens_json" --argjson cost_usd "$cost_json" --argjson model "$model_json" \
+    --argjson usage_partial "$usage_partial_json" --arg stderr "$stderr_text" \
+    --arg stdout_path "$stdout_file" --arg stderr_path "$stderr_file" \
+    --arg verify_stdout_path "$verify_stdout_file" --arg verify_stderr_path "$verify_stderr_file" \
+    '{backend:$backend, task_id:$task_id, duration_seconds:$duration, success:$success,
+      files_changed:$files_changed, lines_added:$lines_added, lines_removed:$lines_removed,
+      tests_passed:$tests_passed, test_exit_status:$test_exit_status, exit_status:$exit_status,
+      retry_count:0, tokens:$tokens, cost_usd:$cost_usd, model:$model,
+      usage_partial:$usage_partial, backend_error:(if $exit_status == 0 or $stderr == "" then null else $stderr end),
+      stdout_path:$stdout_path, stderr_path:$stderr_path,
+      verify_stdout_path:(if $tests_passed == null then null else $verify_stdout_path end),
+      verify_stderr_path:(if $tests_passed == null then null else $verify_stderr_path end),
+      human_review_score:null, review_quality_notes:null}' >> "$results_file"
+done
+
+jq -s --arg generated_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '{schema_version:1, generated_at:$generated_at, results:.}' "$results_file" > "$output_file"
+printf '%s\n' "$output_file"

package/bin/e3d-debate

@@ -0,0 +1,291 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Prototype: run a question through a multi-round debate across several
+# lib/providers/<name> adapters, then ask one of them to synthesize a final
+# answer from the full transcript. Not wired into bin/e3d-pilot or
+# config.schema.json yet -- this is a standalone experiment to see whether
+# automating the manual "ask several models, compare, decide" loop is worth
+# building out further.
+
+# Resolve symlinks so this works when invoked via npm's node_modules/.bin link.
+_src="${BASH_SOURCE[0]}"
+while [[ -L "$_src" ]]; do
+  _dir="$(cd "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" == /* ]] || _src="$_dir/$_src"
+done
+SCRIPT_DIR="$(cd "$(dirname "$_src")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+PROVIDERS_DIR="$REPO_ROOT/lib/providers"
+# shellcheck source=lib/providers/jev.sh
+source "$REPO_ROOT/lib/providers/jev.sh"
+
+DEBATE_PROVIDERS=(claude codex)
+DEBATE_ROUNDS=2
+DEBATE_SYNTHESIZER="claude"
+DEBATE_MAX_WORDS=200
+OUT_DIR=""
+QUESTION=""
+QUESTION_FILE=""
+LINK_REPO=""
+LINK_IDEA=""
+
+usage() {
+  cat <<'EOF'
+e3d-debate "<question>" [--providers claude,codex] [--rounds 2] [--synthesizer claude] [--max-words 200] [--question-file <path>] [--out-dir <dir>] [--repo <path> --idea <idea-id>]
+
+Runs the question through N rounds across the given lib/providers/<name>
+adapters (round 1: independent answers; round 2+: each provider sees every
+other provider's prior-round answer and is asked to rebut or concede), then
+asks --synthesizer to read the full transcript and produce one final answer --
+unless every participant's round-2+ status already converged on "approved",
+in which case the synthesizer call is skipped and the first participant's
+POSITION line is emitted directly (full agreement means everyone would act
+the same, so there is nothing left for a synthesizer to add).
+Prints the transcript and final answer to stdout; also writes transcript.md
+under --out-dir (default: a mktemp dir, path printed at the end).
+
+--question-file reads the question from a file instead of argv -- use it for
+long or heavily quoted/formatted questions that are awkward to pass as a
+single shell argument. --max-words caps each provider's per-round answer
+length (raise it for questions that need real depth, e.g. a multi-part
+strategic review).
+
+--repo <path> and --idea <idea-id> (must be given together) link this
+debate's verdict into that repo's provenance graph as soon as synthesis
+succeeds, via `e3d-pilot ideas note --decision --evidence`. This requires
+--out-dir to be a path inside --repo (e.g. docs/debates/<slug>), since the
+evidence link is a repo-relative path and only durable once that transcript
+is committed. This does not create the idea -- it must already exist.
+
+If TYPESAFE_API_KEY is set, e3d-debate also asks Jev (TypeSafe System One) a
+single Noul question up front -- "is this obvious enough that debate is
+unnecessary?" -- and logs the answer into the transcript as a shadow-mode,
+informational-only signal. It never skips or shortens the debate; this is
+calibration data for a possible future live pre-screen gate (see
+idea-82a5c2225266). No key set means this is silently skipped.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --providers) IFS=',' read -r -a DEBATE_PROVIDERS <<< "$2"; shift 2 ;;
+    --rounds) DEBATE_ROUNDS="$2"; shift 2 ;;
+    --synthesizer) DEBATE_SYNTHESIZER="$2"; shift 2 ;;
+    --max-words) DEBATE_MAX_WORDS="$2"; shift 2 ;;
+    --question-file) QUESTION_FILE="$2"; shift 2 ;;
+    --out-dir) OUT_DIR="$2"; shift 2 ;;
+    --repo) LINK_REPO="$2"; shift 2 ;;
+    --idea) LINK_IDEA="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) QUESTION="$1"; shift ;;
+  esac
+done
+
+if [[ -n "$QUESTION_FILE" ]]; then
+  [[ -f "$QUESTION_FILE" ]] || { echo "error: --question-file not found: $QUESTION_FILE" >&2; exit 1; }
+  QUESTION="$(cat "$QUESTION_FILE")"
+fi
+
+[[ -n "$QUESTION" ]] || { echo "error: question required (see --help)" >&2; exit 1; }
+[[ "$DEBATE_MAX_WORDS" =~ ^[0-9]+$ ]] && (( DEBATE_MAX_WORDS >= 1 )) || { echo "error: --max-words must be a positive integer" >&2; exit 1; }
+[[ "$DEBATE_ROUNDS" =~ ^[0-9]+$ ]] && (( DEBATE_ROUNDS >= 1 )) || { echo "error: --rounds must be a positive integer" >&2; exit 1; }
+(( ${#DEBATE_PROVIDERS[@]} >= 2 )) || { echo "error: need at least 2 --providers to debate" >&2; exit 1; }
+
+for p in "${DEBATE_PROVIDERS[@]}" "$DEBATE_SYNTHESIZER"; do
+  [[ -x "$PROVIDERS_DIR/$p" ]] || { echo "error: no such provider adapter: $PROVIDERS_DIR/$p" >&2; exit 1; }
+done
+
+if [[ -n "$LINK_REPO" || -n "$LINK_IDEA" ]]; then
+  [[ -n "$LINK_REPO" && -n "$LINK_IDEA" ]] || { echo "error: --repo and --idea must be given together" >&2; exit 1; }
+  [[ -d "$LINK_REPO" ]] || { echo "error: --repo not found: $LINK_REPO" >&2; exit 1; }
+  [[ -n "$OUT_DIR" ]] || { echo "error: --out-dir is required (and must be inside --repo) when using --repo/--idea" >&2; exit 1; }
+  mkdir -p "$OUT_DIR"
+  LINK_REPO="$(cd "$LINK_REPO" && pwd)"
+  out_dir_abs="$(cd "$OUT_DIR" && pwd)"
+  case "$out_dir_abs" in
+    "$LINK_REPO"/*) LINK_TRANSCRIPT_REL="${out_dir_abs#"$LINK_REPO"/}/transcript.md" ;;
+    *) echo "error: --out-dir must be inside --repo to be evidence-linkable (got $out_dir_abs, repo $LINK_REPO)" >&2; exit 1 ;;
+  esac
+fi
+
+work_dir="$(mktemp -d "${TMPDIR:-/tmp}/e3d-debate.XXXXXX")"
+transcript_md="$work_dir/transcript.md"
+printf '# Debate\n\n**Question:** %s\n\n' "$QUESTION" > "$transcript_md"
+
+# Jev pre-screen: shadow-mode only (idea-82a5c2225266) -- this NEVER skips or
+# shortens the debate below, it just logs an informational signal into the
+# transcript for later calibration of whether Jev's obviousness judgment is
+# trustworthy enough to ever gate on. Silently skipped with no
+# TYPESAFE_API_KEY; a failed call is logged and otherwise ignored.
+if jev_available; then
+  jev_state="$(jq -ncS --arg q "$QUESTION" '{question:$q}')"
+  jev_questions="$(jq -ncS '{
+    obviousness: {
+      type: "noul",
+      instructions: "Is this question'\''s answer obvious enough that informed, knowledgeable people would not meaningfully disagree, or does it need genuine multi-perspective debate to reach a well-reasoned answer?",
+      criteria: {
+        "true": "The answer is clear-cut -- reasonable experts would converge on the same conclusion without needing to compare independent perspectives.",
+        "false": "The answer involves real tradeoffs, judgment calls, or contestable premises where different informed people could reasonably land in different places."
+      }
+    }
+  }')"
+  jev_response=""
+  jev_response="$(jev_call "jev-latest" "$jev_state" "$jev_questions")" || jev_response=""
+  if [[ -n "$jev_response" ]]; then
+    # Noul answers carry only a `noul` probability, no `confidence` field
+    # (that's Choice/Score-only) -- see https://docs.typesafe.ai/api.md.
+    jev_noul="$(jq -r '.answers.obviousness.noul // "unknown"' <<< "$jev_response" 2>/dev/null || echo "unknown")"
+    echo "=== Jev pre-screen (shadow mode, informational only -- does not skip the debate): obviousness noul=$jev_noul ===" >&2
+    printf '**Jev pre-screen (shadow mode, informational only):** obviousness noul=%s (1.0 = clearly obvious, 0.0 = clearly needs debate) -- logged for calibration, does not affect whether this debate runs.\n\n' "$jev_noul" >> "$transcript_md"
+  fi
+fi
+
+declare -A LAST_ANSWER
+converged=0
+converged_at_round=0
+
+for ((round = 1; round <= DEBATE_ROUNDS; round++)); do
+  echo "=== Round $round ===" >&2
+  pids=()
+  for provider in "${DEBATE_PROVIDERS[@]}"; do
+    prompt_file="$work_dir/round${round}-${provider}.prompt.md"
+    out_file="$work_dir/round${round}-${provider}.out"
+    status_file="$work_dir/round${round}-${provider}.status"
+    {
+      if (( round == 1 )); then
+        printf 'You are one of several AI models independently answering a question, before comparing notes with the others in later rounds.\n\n'
+        printf 'Question: %s\n\n' "$QUESTION"
+        printf 'Give your best direct answer with your key reasoning and any load-bearing assumptions. Be decisive, not hedgy. Under %d words.\n' "$DEBATE_MAX_WORDS"
+      else
+        printf 'You are in round %d of a structured debate among several AI models answering one question.\n\n' "$round"
+        printf 'Question: %s\n\n' "$QUESTION"
+        printf 'Here is what each participant said in the previous round:\n\n'
+        for other in "${DEBATE_PROVIDERS[@]}"; do
+          printf -- '--- %s (previous round) ---\n%s\n\n' "$other" "${LAST_ANSWER[$other]}"
+        done
+        printf 'Critically evaluate the other answers against your own. If your prior position holds up, restate it and rebut what'\''s wrong in the others. If you'\''ve changed your mind, say so plainly and why. Under %d words.\n\n' "$DEBATE_MAX_WORDS"
+        printf 'End with exactly these two lines, in this exact format:\n'
+        printf 'POSITION: <one-sentence current answer>\n'
+        printf 'status: approved|revise\n'
+        printf '("approved" = a person acting on your answer and a person acting on every other participant'\''s answer would do the same thing -- extra caveats, framing, or added nuance do NOT count as disagreement. "revise" = someone following your answer would act differently than someone following at least one other participant'\''s answer.)\n'
+      fi
+    } > "$prompt_file"
+    (
+      set +e
+      "$PROVIDERS_DIR/$provider" "$prompt_file" > "$out_file" 2>"$work_dir/round${round}-${provider}.stderr"
+      echo $? > "$status_file"
+    ) &
+    pids+=($!)
+  done
+  for pid in "${pids[@]}"; do wait "$pid" || true; done
+
+  for provider in "${DEBATE_PROVIDERS[@]}"; do
+    out_file="$work_dir/round${round}-${provider}.out"
+    status_file="$work_dir/round${round}-${provider}.status"
+    status="$(cat "$status_file" 2>/dev/null || echo 1)"
+    if [[ "$status" == "0" && -s "$out_file" ]]; then
+      answer="$(cat "$out_file")"
+    else
+      answer="(provider $provider failed in round $round -- see $work_dir/round${round}-${provider}.stderr)"
+    fi
+    LAST_ANSWER[$provider]="$answer"
+    printf '## Round %d -- %s\n\n%s\n\n' "$round" "$provider" "$answer" >> "$transcript_md"
+    printf -- '--- Round %d / %s ---\n%s\n\n' "$round" "$provider" "$answer"
+  done
+
+  if (( round >= 2 )); then
+    statuses=()
+    for provider in "${DEBATE_PROVIDERS[@]}"; do
+      s="$(grep -m1 -E '^status: (approved|revise)$' <<< "${LAST_ANSWER[$provider]}" | sed -E 's/^status: //' || true)"
+      [[ "$s" == "approved" || "$s" == "revise" ]] || s="revise"
+      statuses+=("$s")
+    done
+    if "$REPO_ROOT/lib/negotiate/convergence" "${statuses[@]}" >/dev/null 2>&1; then
+      converged=1
+      converged_at_round=$round
+      echo "=== Converged after round $round -- all participants agree, skipping remaining rounds ===" >&2
+      break
+    fi
+  fi
+done
+
+if (( converged == 1 )); then
+  rounds_ran_note="converged after round $converged_at_round of a max $DEBATE_ROUNDS -- all participants ended that round agreeing"
+else
+  rounds_ran_note="ran the full $DEBATE_ROUNDS rounds without every participant converging"
+fi
+
+synth_prompt="$work_dir/synthesis.prompt.md"
+{
+  printf 'Below is the full transcript of a debate between multiple AI models answering one question for a human who needs a single, decisive answer (%s).\n\n' "$rounds_ran_note"
+  printf 'Question: %s\n\n' "$QUESTION"
+  cat "$transcript_md"
+  printf '\nRead the transcript and produce a final answer. Output exactly this format:\n'
+  printf 'FINAL ANSWER: <2-4 decisive sentences>\n'
+  printf 'CONSENSUS: <full | majority | split>\n'
+  printf 'DISSENT: <one line on any remaining disagreement worth flagging, or "none">\n'
+} > "$synth_prompt"
+
+synth_out="$work_dir/synthesis.out"
+
+# When every participant converged on "approved" in the final round, the
+# synthesizer call adds no information -- everyone already agreed they'd act
+# the same as everyone else. Skip it and emit the first participant's
+# POSITION line directly (order = --providers order, deterministic).
+fast_synthesis=0
+if (( converged == 1 )); then
+  first_provider="${DEBATE_PROVIDERS[0]}"
+  fast_position="$(grep -m1 -E '^POSITION: ' <<< "${LAST_ANSWER[$first_provider]}" | sed -E 's/^POSITION: //')"
+  if [[ -n "$fast_position" ]]; then
+    fast_synthesis=1
+    printf 'FINAL ANSWER: %s\nCONSENSUS: full\nDISSENT: none\n' "$fast_position" > "$synth_out"
+  fi
+fi
+
+if (( fast_synthesis == 1 )); then
+  synth_status=0
+  echo "=== Synthesis (fast path -- all participants converged in round $converged_at_round, no synthesizer call) ===" >&2
+else
+  set +e
+  "$PROVIDERS_DIR/$DEBATE_SYNTHESIZER" "$synth_prompt" > "$synth_out" 2>"$work_dir/synthesis.stderr"
+  synth_status=$?
+  set -e
+  echo "=== Synthesis ($DEBATE_SYNTHESIZER) ===" >&2
+fi
+
+synth_ok=0
+if [[ $synth_status -eq 0 && -s "$synth_out" ]]; then
+  synth_ok=1
+  cat "$synth_out"
+  synth_label="$DEBATE_SYNTHESIZER"
+  (( fast_synthesis == 1 )) && synth_label="fast path, no LLM call"
+  printf '\n## Synthesis (%s)\n\n%s\n' "$synth_label" "$(cat "$synth_out")" >> "$transcript_md"
+else
+  echo "error: synthesis provider failed -- see $work_dir/synthesis.stderr" >&2
+fi
+
+if [[ -n "$OUT_DIR" ]]; then
+  mkdir -p "$OUT_DIR"
+  cp "$transcript_md" "$OUT_DIR/transcript.md"
+  echo "transcript: $OUT_DIR/transcript.md" >&2
+else
+  echo "transcript: $transcript_md" >&2
+fi
+
+if [[ -n "$LINK_REPO" ]]; then
+  if [[ "$synth_ok" -eq 1 ]]; then
+    provider_list="$(IFS=,; echo "${DEBATE_PROVIDERS[*]}")"
+    note_text="$(printf 'e3d-debate (%s, %s) verdict:\n\n%s' "$provider_list" "$rounds_ran_note" "$(cat "$synth_out")")"
+    if "$REPO_ROOT/bin/e3d-pilot" ideas note --repo "$LINK_REPO" --decision \
+        --evidence "$LINK_TRANSCRIPT_REL" "$LINK_IDEA" "$note_text" \
+        --actor "e3d-debate:$provider_list" >&2; then
+      echo "provenance: linked to $LINK_IDEA in $LINK_REPO (evidence_ref=$LINK_TRANSCRIPT_REL)" >&2
+    else
+      echo "warning: failed to link debate evidence onto $LINK_IDEA -- transcript is still at $OUT_DIR/transcript.md, link it manually with 'e3d-pilot ideas note --evidence'" >&2
+    fi
+  else
+    echo "warning: skipping provenance link -- synthesis failed, no verdict to record" >&2
+  fi
+fi

package/bin/e3d-grok-workers

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=lib/scoring/fanout.sh
+source "$REPO_ROOT/lib/scoring/fanout.sh"
+
+usage() {
+  cat <<'EOF'
+Usage: e3d-grok-workers --repo <path> --candidates <json> --output <json>
+       [--provider <name>] [--workers <3..5>] [--top <n>]
+
+Read-only candidate scoring. `--provider` defaults to grok-build; any
+lib/providers adapter is accepted. Scoring never executes a candidate.
+EOF
+}
+die() { printf 'error: %s\n' "$*" >&2; exit 1; }
+
+repo="" candidates_file="" output_file="" provider="grok-build" workers=3 top=5
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo) repo="${2:-}"; shift 2 ;;
+    --candidates) candidates_file="${2:-}"; shift 2 ;;
+    --output) output_file="${2:-}"; shift 2 ;;
+    --provider) provider="${2:-}"; shift 2 ;;
+    --workers) workers="${2:-}"; shift 2 ;;
+    --top) top="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[[ -n "$repo" && -n "$candidates_file" && -n "$output_file" ]] || { usage >&2; exit 1; }
+[[ "$workers" =~ ^[0-9]+$ ]] && (( workers >= 3 && workers <= 5 )) || die "--workers must be between 3 and 5"
+[[ "$top" =~ ^[0-9]+$ ]] && (( top > 0 )) || die "--top must be a positive integer"
+[[ -d "$repo" ]] || die "repository not found: $repo"
+repo="$(cd "$repo" && pwd -P)"
+jq -e 'type == "array" and length > 0 and all(.[]; (.id | type == "string") and (.id | length > 0))' "$candidates_file" >/dev/null \
+  || die "candidates must be a non-empty JSON array with string id fields"
+[[ "$(jq '[.[].id] | length == (unique | length)' "$candidates_file")" == "true" ]] || die "candidate ids must be unique"
+
+artifact_dir="${output_file%.json}.artifacts"
+raw_output="$(mktemp "${TMPDIR:-/tmp}/e3d-scoring-raw.XXXXXX")"
+status=0
+if ! scoring_run_fanout "$repo" "$provider" "$candidates_file" "$workers" "$artifact_dir" "$raw_output"; then
+  status=$?
+fi
+[[ -s "$raw_output" ]] || { rm -f "$raw_output"; die "all scoring workers failed; inspect $artifact_dir"; }
+
+jq --argjson top "$top" '
+  . + {
+    selected: (.ranked[:$top]),
+    downstream:"frontier review then existing negotiation; no automatic execution"
+  }
+' "$raw_output" > "$output_file"
+rm -f "$raw_output"
+printf '%s\n' "$output_file"
+exit "$status"