feat(idea-spark): quality gauntlet upgrades + run-state navigator + SKILL.md slimdown

ResearchStudio-Idea/skills/idea_spark/references/intent-recognition.md

@@ -47,21 +47,27 @@ Output:
 }
 ```
 
-## Collision mode — signature extraction
+## Collision mode — signature + alias extraction
 
 Use the same [CLASSIFY_FAST] LLM with this prompt:
 
 ```
-You read a candidate research idea and extract 3-5 signature terms — tightly worded phrases for phrase matching.
+You read a candidate research idea and extract TWO term sets: 3-5 signature terms (the candidate's own vocabulary) and 2-4 alias terms (other communities' names for the same mechanism).
 
-Return JSON: {"signature_terms": ["...", "..."]}
+Return JSON: {"signature_terms": ["...", "..."], "alias_terms": ["...", "..."]}
 
-Rules:
+signature_terms rules:
 - Each term is 3-7 words.
 - Cover (a) the mechanism, (b) the claim, (c) the setting/setup. One term per facet, plus 1-2 specific identifiers (e.g. dataset name, theorem name).
 - Avoid generic terms ("deep learning", "transformer") — they retrieve too much noise.
 - Prefer noun phrases over verb phrases.
-- These terms will be sent verbatim to a BM25 retriever AND embedded for cosine search.
+- These terms will be sent verbatim to a BM25 retriever AND embedded for cosine search, over a RECENT window (scoop risk).
+
+alias_terms rules:
+- Each term is 3-7 words, naming the SAME core mechanism in a vocabulary the candidate's own community does not use.
+- This is a parametric-knowledge step: "if a reward-modeling / classical-CV / RL / NLP / theory group had built this mechanism 2-3 years ago, what would their titles call it?" Same-mechanism ancestors usually exist under a different name — a "goal-image conditioned scorer for task completion" is elsewhere a "goal-conditioned success detector" or "goal-image reward model".
+- Do NOT paraphrase signature_terms — a paraphrase retrieves what the signature channel already retrieves. Change the community, not the wording.
+- These terms run over a MULTI-YEAR window (renamed-ancestor risk).
 ```
 
 ### Worked example
@@ -82,6 +88,11 @@ Output:
     "score function singularity boundary",
     "training-free sampling acceleration",
     "EDM truncated training"
+  ],
+  "alias_terms": [
+    "annealed Langevin early stopping",
+    "SDE solver step-size adaptivity bound",
+    "curriculum over noise levels"
   ]
 }
 ```

ResearchStudio-Idea/skills/idea_spark/references/setup.md

@@ -0,0 +1,35 @@
+# Idea Spark — Setup (first use only)
+
+Read this once when installing the skill; at run time SKILL.md never needs this file. The skill's Phase 0 + Phase 3.1 retrieval needs API credentials for 2 of the 4 connectors. Without them the affected connectors are skipped and the orchestrator continues with whichever connectors are available — but it prints a prominent **CONNECTORS DEGRADED** banner and writes a `.connectors_degraded` marker so a partial run is never mistaken for a full one.
+
+0. **Set two shell variables once per session** — where this skill is installed, and where run outputs should go. Neither depends on the harness:
+   ```bash
+   SKILL_DIR=~/.claude/skills/idea-spark            # Claude Code default; Codex CLI: ~/.codex/skills/idea_spark; else wherever this folder lives
+   RUN_DIR="$PWD/idea_run" && mkdir -p "$RUN_DIR"   # ANY absolute directory you want the per-phase outputs in
+   ```
+   `RUN_DIR` is purely an output anchor — the orchestrator only ever sees the absolute `--out` paths you pass, so the variable *name* does not matter (Claude Code sessions can reuse the injected `CLAUDE_PROJECT_DIR` as their `RUN_DIR`). The orchestrator hard-fails early with an actionable message when a path argument contains an unexpanded `$variable`, collapses to filesystem root (empty expansion, e.g. `/phase0`), or is a relative `--out` — instead of a confusing `FileNotFoundError` mid-run.
+
+1. **Install the skill**: `idea-spark` — Phase 0 literature search runs from its bundled connector scripts (no separate sub-skill). On non-Claude-Code harnesses, clone or copy this folder anywhere and point `SKILL_DIR` at it.
+
+2. **Install Python deps** (cross-platform — macOS & Linux): `python3 -m pip install feedparser openreview-py beautifulsoup4 pymupdf`. Four lean packages. Skipping this is the most common first-run failure: `arxiv` errors with `package not installed`, and missing `pymupdf`/`beautifulsoup4` silently degrades every full-text fetch to abstract-only.
+   - **PEP 668 systems** (recent macOS/Homebrew & Ubuntu 23.04+) reject a bare `pip install` with `externally-managed-environment`. Two safe options:
+     - **venv (recommended):** `python3 -m venv .venv && source .venv/bin/activate && pip install feedparser openreview-py beautifulsoup4 pymupdf` — then launch every phase **from this same activated shell** (see the connector-degradation note below).
+     - **user install:** `python3 -m pip install --user --break-system-packages feedparser openreview-py beautifulsoup4 pymupdf`.
+   - **Use the SAME interpreter everywhere.** `check_connectors` and the phase commands must run under the one Python that has these packages. A package installed for `pip3` but launched under a different `python3` (or a background/non-login shell that drops `--user` site-packages) will pass `check_connectors` yet skip `arxiv`/`openreview` at runtime — the run prints a loud **CONNECTORS DEGRADED** banner and drops a `.connectors_degraded` marker when that happens.
+   - **Optional deps (only if you want the extras):** PDF compilation of the idea card needs **xelatex** *or* **tectonic** (macOS `brew install --cask mactex-no-gui` or `brew install tectonic`; Ubuntu `sudo apt-get install texlive-xetex` or `cargo install tectonic`). Without either, the `.md`/`.tex` cards are still written and only the PDF is skipped (with a hint). The optional pipeline-diagram image needs the `azure-*` packages; absent, it is skipped silently.
+
+3. **Copy** the env template at the project root: `cp .env.template .env`.
+
+4. **Fill in keys** (priority order — by impact on retrieval quality):
+
+| Key | Required for | How to get |
+|---|---|---|
+| `OPENREVIEW_USER` + `OPENREVIEW_PASS` | OpenReview connector (in-review forward signal). Without these, openreview is silently skipped — you lose the 0-6mo in-review window unique to it. | Free signup at https://openreview.net |
+| `SEMANTICSCHOLAR_API_KEY` | Semantic Scholar connector at usable rate. Anonymous tier (~100 req/5min) hits 429 on Phase 0 multi-query batches; with key it's stable at 1 req/s. | Free apply at https://www.semanticscholar.org/product/api#api-key-form (≈24h review). Connector still runs anonymously without it but will frequently 429. |
+| `OPENALEX_API_KEY` | Optional, premium rate. Polite-pool already works for typical Phase 0 load. | Apply at openalex.org if you exceed polite limits. |
+
+5. **Verify** (from the SAME shell/venv you will launch phases from): `python3 "$SKILL_DIR/scripts/run.py" check_connectors` — should show ✅ for all 4 connectors AND the two full-text fetch deps (`pymupdf`, `beautifulsoup4`). If you verify in one shell but run phases in another, the package set can differ — keep it one shell.
+
+6. **The orchestrator auto-loads `.env`** at runtime (walks up from skill dir to find `.env`), so you do NOT need to `source .env` in your shell. Shell-set env vars take precedence over `.env` values, so you can override on the fly.
+
+If a connector shows ❌, it's either missing creds (fix in `.env`) or missing the pip package (the error message tells you which `pip install` to run). If a full-text dep shows ⚠️, run `pip install feedparser openreview-py beautifulsoup4 pymupdf`.

ResearchStudio-Idea/skills/idea_spark/references/system-prompts/critique.txt

@@ -1,13 +1,13 @@
 You are running Phase 3.2 — Audit-and-Verdict — of IdeaSpark.
 
-Step 3.2 produces a corpus-anchored audit on the Phase 2.2 candidate. It runs four checks (gap_closure_reject_check / recipe_application_check / anti_pattern_check / paper_pointed_threat), emits a verdict + revision_targets, and does NOT auto-revise (Phase 3.3 applies revisions in a separate call).
+Step 3.2 produces a corpus-anchored audit on the Phase 2.2 candidate. It runs five checks (gap_closure_reject_check / recipe_application_check / anti_pattern_check / paper_pointed_threat / falsification_structure_check), emits a verdict + revision_targets, and does NOT auto-revise (Phase 3.3 applies revisions in a separate call).
 
 Inputs (explicit paths):
 - `$RUN_DIR/phase2_generate/phase2_generate_output.json` — the Phase 2.2 candidate (12 flat fields).
 - `$RUN_DIR/phase2_select/phase2_select_output.json` — the Phase 2.1 spec (selected_gaps with chosen_pattern_id).
 - **One sub-pattern card per `gap_closure[]` entry**: `references/ideation-sub-patterns/<C##>.md` where `<C##>` is the **leading cluster code C00 through C30** of that entry's `sub_pattern` value (the value is formatted `C## (parent pattern name)`, so strip everything after the code — e.g. `C12 (Substitute the Operator or Representation)` → open `C12.md`). NOT a parent-pattern-named file. Read `## Tactical failure mode` + ALL bullets under `## Examples → ### Reject lessons` verbatim. The lessons are paper-agnostic distillations (no `[Reject]` example headers, no `paper_id` references) so quote the bullet text directly.
 - `$RUN_DIR/phase0/lit_table.md` — used for paper-pointed threat search.
-- `$RUN_DIR/phase3_collision/collision_hits.json` — recently retrieved papers via mechanism-specific signature_terms.
+- `$RUN_DIR/phase3_collision/collision_hits.json` — mechanism-specific retrieval, TWO channels per hit's `collision_channel` field: `signature` (candidate's own vocabulary, recent window — contemporaneous scoop risk) and `alias` (other communities' names for the same mechanism, multi-year window — renamed-ancestor risk). Alias-channel hits are older by design; do NOT discount a threat for being 2-3 years old — a same-mechanism ancestor subsumes the candidate regardless of age.
 - `references/anti-patterns.md` — 3 reject-favored compositions with required mitigations.
 
 Output (JSON):
@@ -59,8 +59,19 @@ Output (JSON):
   "paper_pointed_threat": {
     "threat_paper_id": "<paper_id from lit_table or collision_hits, or 'no_threat_found'>",
     "threat_source": "lit_table | collision_hits | n/a",
+    "threat_channel": "<for collision_hits threats: the hit's collision_channel value (signature | alias); null otherwise>",
     "subsumption_argument": "<one paragraph: what specific result of threat_paper_id makes the candidate's claim stand or fall. null if no_threat_found.>",
-    "addressable_via": "<one sentence on which candidate field would need to change to dodge this threat, or null if exact-mechanism overlap (unaddressable) or null if no_threat_found>"
+    "addressable_via": "<one sentence on which candidate field would need to change to dodge this threat, or null if exact-mechanism overlap (unaddressable) or null if no_threat_found>",
+    "parametric_family_concern": "<SOFT SIGNAL, from your own knowledge, NOT from the retrieved pool: if the candidate's core mechanism plainly resembles an older, named research family the pool did not surface (e.g. 'goal-conditioned success detectors', 'learned value-function reward models'), NAME THE FAMILY and 1-2 vocabulary phrases a scoop-check should query — do NOT cite specific papers from memory (titles/authors/years hallucinate; family names don't). null when the pool covered the mechanism's obvious relatives. This field NEVER feeds the hard floor or the verdict — it flows to Phase 4's reviewer_concerns_and_responses as a 'run a scoop-check on X before investing' flag.>"
+  },
+
+  "falsification_structure_check": {
+    "minimal_experiment_named": "<yes | no — does the paragraph name a concrete minimal experiment (setup + comparison), not just 'we will evaluate'>",
+    "outcome_metric_named": "<yes | no — does it name the downstream task-outcome metric AND its qualitative direction if the candidate works>",
+    "load_bearing_variable": "<quote the ONE named quantity the mechanism claim pivots on (a gradient norm, an information-gain term, a logit divergence, a learned threshold, a representational direction, ...), or 'absent' if no single variable is named>",
+    "negative_control_target": "<'outcome_metric' when the negative-control intervention on the load-bearing variable predicts the DOWNSTREAM outcome metric returns to baseline; 'tautological' when the predicted effect is the load-bearing variable's own value or a quantity analytically derived from it (a control of the form \"intervene on X → X becomes 0\" tests a definition, not a mechanism); 'absent' when no negative control is stated>",
+    "verdict": "sound | deficient | borderline",
+    "reasoning": "<1-2 sentences: which sub-answer drove the verdict. 'sound' requires ALL of: minimal_experiment_named=yes, outcome_metric_named=yes, load_bearing_variable quoted (not absent), negative_control_target=outcome_metric. Any 'no'/'absent'/'tautological' → deficient. borderline is reserved for a named-but-ambiguous variable or a control whose target metric is arguably-but-not-explicitly the outcome.>"
   },
 
   "verdict": "advance | revise | abandon",
@@ -69,10 +80,10 @@ Output (JSON):
 
   "revision_targets": [
     {
-      "scope": "tactical | sub_pattern",
-      "field": "<for tactical: which Phase 2.2 candidate field; for sub_pattern: which gap_closure[] entry's sub_pattern needs swapping (cite gap verbatim)>",
+      "scope": "tactical | sub_pattern | falsification",
+      "field": "<for tactical: which Phase 2.2 candidate field; for sub_pattern: which gap_closure[] entry's sub_pattern needs swapping (cite gap verbatim); for falsification: always 'falsification_prediction'>",
       "issue": "<which check / lesson triggered>",
-      "fix_direction": "<concrete: what Phase 3.3 should change. For tactical: field-level edit. For sub_pattern: which specific sibling sub-pattern under the same parent fits better and why.>"
+      "fix_direction": "<concrete: what Phase 3.3 should change. For tactical: field-level edit. For sub_pattern: which specific sibling sub-pattern under the same parent fits better and why. For falsification: which structural element is missing/tautological (per falsification_structure_check) — the rewrite must keep the SAME experiment and claim, only repairing the structure.>"
     }
   ]
 }
@@ -103,7 +114,8 @@ Heuristics:
 - **Choose revise** when at least one borderline / partial finding hits a load-bearing structural property (core_mechanism's central argument, anti_pattern mitigation strength, addressable threat via specific candidate field).
 - **Choose revise** when `recipe_application_check.verdict = bypassed` — the cited cluster's signature move is absent from core_mechanism, so the idea was built from the parent pattern's generic gist rather than the tactic that was supposed to make it sharp (the leading cause of incremental output, and the citation string cannot catch it because in this taxonomy the sub_pattern only names the parent). revision_target: either swap the sub_pattern to the sibling cluster whose tactical move core_mechanism actually performs, or rework core_mechanism to instantiate the cited move.
 - **Choose revise** when paper_pointed_threat exists AND `addressable_via` names a specific candidate field.
-- **Choose advance** when all checks are clear / holds / null / no_threat_found.
+- **Choose revise** when `falsification_structure_check.verdict = deficient` — the falsifiability commitment is the candidate's single most Reject-predictive field, and a structural hole in it (no load-bearing variable, tautological negative control) is repairable without touching the experiment or the claim. Emit ONE revision_target with `scope = "falsification"`, `field = "falsification_prediction"`, and a fix_direction naming exactly which structural element to repair. This is the ONLY route by which the kill-switch field may change; the rewrite is applied by Phase 3.3's dedicated `rewrite_falsification` op, gated by the merger on this audit's authorization, and MUST be re-audited (see "Falsification re-audit mode" below) before Phase 4.
+- **Choose advance** when all checks are clear / holds / null / no_threat_found / sound.
 
 Hard rules:
 
@@ -117,4 +129,23 @@ Hard rules:
 
 5. **recipe_application_check is semantic, not a citation check**. A separate deterministic validator (subpattern_citation_consistency) already confirms each sub_pattern citation points at a real C## cluster under its cited parent — assume that passed. In this taxonomy the sub_pattern string carries only `C## (parent display name)`, so a clean citation does NOT prove the cluster's own card was opened. recipe_application_check answers the harder question automation cannot: even with a correctly-cited code, does core_mechanism actually perform that C##.md card's `## Tactical pattern` signature move, or did the generator read the parent pattern's name and produce something generic? Judge the MECHANISM against the card text, not the citation string.
 
+6. **`scope = "falsification"` is exclusively for falsification_structure_check findings**. Do NOT use it to make the experiment cheaper, swap the metric, or weaken the claim — those are anti-substitution violations the merger will reject. The rewrite repairs STRUCTURE only (name the load-bearing variable, fix a tautological negative control, state the missing minimal experiment / metric direction) while preserving the experiment, the metric, and the claim already committed to. `compute_budget` has NO revision route under any scope.
+
 Output path: `$RUN_DIR/phase3_critique/phase3_critique_output.json`.
+
+---
+
+### Falsification re-audit mode (single-check re-run after a falsification rewrite)
+
+When Phase 3.3 applied a `rewrite_falsification` patch (and only then), the rewritten kill-switch field must clear the structure check before Phase 4. This is a SEPARATE, bounded LLM call:
+
+- **Inputs**: `$RUN_DIR/phase3_revise/final_candidate.json` (read ONLY `falsification_prediction` + `core_mechanism` for context) + this prompt's falsification_structure_check spec. Do NOT re-run the other four checks; their findings stand.
+- **Output** (`$RUN_DIR/phase3_critique/falsification_reaudit.json`):
+
+{
+  "falsification_structure_check": { <same schema as above, evaluated on the REWRITTEN paragraph> },
+  "verdict": "advance | abandon",
+  "verdict_rationale": "<1-2 sentences>"
+}
+
+- **Routing**: `sound` (or `borderline` with the load-bearing variable clearly named) → `advance`, proceed to Phase 4 using `final_candidate.json`. `deficient` again → `abandon` (write `phase_3_failed.md` naming both the original deficiency and why the rewrite still fails). Exactly ONE rewrite attempt per run — a second falsification revision_target is a process error.

ResearchStudio-Idea/skills/idea_spark/references/system-prompts/ideate_generate.txt

@@ -198,6 +198,11 @@ Output (strict JSON):
     "<3-5 entries total; each a 3-7 word phrase>",
     "<3-7 word phrase>",
     "..."
+  ],
+
+  "alias_terms": [
+    "<2-4 entries; each a 3-7 word phrase naming the SAME core mechanism in ANOTHER community's vocabulary>",
+    "..."
   ]
 }
 
@@ -233,7 +238,19 @@ Notes:
 - `signature_terms[]`: 3-5 entries, 3-7 words each. Cover (a) the mechanism,
   (b) the claim, (c) the setting/setup. No verbatim title strings. No
   generic terms ("deep learning", "transformer"). These get sent verbatim to
-  the BM25 retriever in Phase 3.1 collision check.
+  the BM25 retriever in Phase 3.1 collision check (recent window).
+- `alias_terms[]`: 2-4 entries, 3-7 words each — how OTHER research
+  communities would name this candidate's core mechanism. This is a
+  PARAMETRIC-KNOWLEDGE step, not a paraphrase step: ask "if a reward-modeling
+  / classical-CV / RL / NLP / theory group had built this same mechanism 2-3
+  years ago, what would their papers' titles call it?" and write those names
+  (e.g. a "goal-image conditioned scorer for task completion" is, in other
+  vocabularies, a "goal-conditioned success detector" / "goal-image reward
+  model"). Do NOT reuse signature_terms vocabulary or the candidate's own
+  domain wording — the whole point is the words your community does NOT use.
+  Phase 3.1 runs these over a multi-year window to catch same-mechanism
+  ancestors that renamed the idea; a paraphrased signature term catches
+  nothing the signature channel didn't already catch.
 - `main_pattern` per entry comes from Phase 2.1; `sub_pattern` is picked
   in this phase's sub-step a. There is no separate `patterns_used[]` field.