feat(tui): select refine source-evidence policy; document default GitHub escalation

- TUI: picking Refine now opens a "source evidence policy" sub-menu (RefineOptions)
  with three presets — auto (paper-first, escalate to GitHub), GitHub-upfront
  (--evidence-refs), and no-web (--no-evidence) — so the evidence behaviour is
  selectable in the TUI, not just via CLI flags.
- docs: clarify the default — GitHub IS searched, but only as autonomous
  escalation on a second stall; --evidence-refs pulls it to the first pass.

Gate green: lint, build, 87/87 tests, smoke.

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

Author: grandchildrice

docs/visioned-self-improvement-changelog.md

@@ -328,6 +328,11 @@ without losing coherence:
   source gaps) and calls `ensureEvidence`; the cache, policy, and accumulation
   live entirely in `lib/evidence.ts`. The evidence→amend-only invariant is
   unchanged.
+- **Control surface.** The policy is selectable both ways: CLI flags
+  `--evidence-refs` (search GitHub from the first pass) / `--no-evidence` (offline,
+  spec-only), and a TUI **Refine → source evidence policy** sub-menu offering the
+  same three presets (auto / GitHub-upfront / no-web). Default in both:
+  paper-first, auto-escalate to GitHub only if the paper doesn't close the gaps.
 
 ## References
 

lib/tui/app.ts

@@ -147,18 +147,42 @@ function SceneList({ onPick, onBack }: { onPick: (id: string) => void; onBack: (
     </${Box}>`;
 }
 
-function SceneAction({ id, onRun, onBack }: { id: string; onRun: (args: string[]) => void; onBack: () => void }) {
+function SceneAction({ id, onRun, onRefine, onBack }: { id: string; onRun: (args: string[]) => void; onRefine: () => void; onBack: () => void }) {
   useInput((_input: string, key: { escape: boolean }) => { if (key.escape) onBack(); });
-  const items: { label: string; value: string[] | 'back' }[] = [
+  type Act = string[] | 'back' | 'refine';
+  const items: { label: string; value: Act }[] = [
     { label: 'View    — open in the browser', value: ['check', id] },
-    { label: 'Refine  — 3D ⇄ implementation loop (improve + verify)', value: ['refine', id] },
+    { label: 'Refine  — 3D ⇄ implementation loop (improve + verify)', value: 'refine' },
     { label: 'Push    — open a PR to the gallery', value: ['upload', id] },
     { label: 'Back', value: 'back' },
   ];
+  const pick = (it: { value: Act }): void => {
+    if (it.value === 'back') onBack();
+    else if (it.value === 'refine') onRefine();
+    else onRun(it.value);
+  };
   return html`
     <${Box} flexDirection="column">
       <${Text}>Scene: <${Text} color="cyan" bold>${id}</${Text}></${Text}>
+      <${Box} marginTop=${1}><${SelectInput} items=${items} onSelect=${pick} /></${Box}>
+    </${Box}>`;
+}
+
+// Refine sub-menu: pick how the closed loop should gather source evidence when it
+// stalls (the CLI's --evidence-refs / --no-evidence as selectable presets).
+function RefineOptions({ id, onRun, onBack }: { id: string; onRun: (args: string[]) => void; onBack: () => void }) {
+  useInput((_input: string, key: { escape: boolean }) => { if (key.escape) onBack(); });
+  const items: { label: string; value: string[] | 'back' }[] = [
+    { label: 'Auto evidence   — paper first, escalate to GitHub if needed (default)', value: ['refine', id] },
+    { label: 'GitHub upfront  — also search reference implementations from the start', value: ['refine', id, '--evidence-refs'] },
+    { label: 'No web evidence — refine from the spec alone (offline)', value: ['refine', id, '--no-evidence'] },
+    { label: 'Back', value: 'back' },
+  ];
+  return html`
+    <${Box} flexDirection="column">
+      <${Text}>Refine <${Text} color="cyan" bold>${id}</${Text}> — source evidence policy</${Text}>
       <${Box} marginTop=${1}><${SelectInput} items=${items} onSelect=${(it: { value: string[] | 'back' }) => (it.value === 'back' ? onBack() : onRun(it.value))} /></${Box}>
+      <${Box} marginTop=${1}><${Text} dimColor>Evidence is cached &amp; reused across runs; it only feeds amend, never the reproduce graders.</${Text}></${Box}>
     </${Box}>`;
 }
 
@@ -184,6 +208,10 @@ function App() {
     body = html`<${SceneList} onBack=${() => setScreen('menu')} onPick=${(id: string) => { setPicked(id); setScreen('sceneAction'); }} />`;
   } else if (screen === 'sceneAction') {
     body = html`<${SceneAction} id=${picked} onBack=${() => setScreen('scenes')}
+      onRefine=${() => setScreen('refineOpts')}
+      onRun=${(args: string[]) => { setRunArgs(args); setScreen('running'); }} />`;
+  } else if (screen === 'refineOpts') {
+    body = html`<${RefineOptions} id=${picked} onBack=${() => setScreen('sceneAction')}
       onRun=${(args: string[]) => { setRunArgs(args); setScreen('running'); }} />`;
   } else if (screen === 'running') {
     body = html`<${Runner} args=${runArgs} onBack=${() => setScreen('menu')} />`;