@ara-commons/ara-skills 0.3.0 → 0.4.0

package/README.md

@@ -1,12 +1,13 @@
 # @ara-commons/ara-skills
 
-One-command installer for the three **Agent-Native Research Artifact (ARA)** skills:
+One-command installer for the four **Agent-Native Research Artifact (ARA)** skills:
 
 | Skill | Invoke | What it does |
 |-------|--------|--------------|
 | `compiler`         | `/compiler <input>`        | Convert a paper, repo, or notes into a complete ARA artifact |
 | `research-manager` | `/research-manager`        | Post-session recorder that captures decisions, dead ends, and claims |
 | `rigor-reviewer`   | `/rigor-reviewer <dir>`    | ARA Seal Level 2 semantic epistemic review across six dimensions |
+| `research-visualizer` | `/research-visualizer <dir>` | Render an ARA into one interactive, self-contained trajectory.html |
 
 ## Quick start
 
@@ -64,4 +65,4 @@ In dev mode the CLI reads skills from the sibling `../../skills/` directory. On
 
 ## Upstream source of truth
 
-The three skill directories live at the repo root under `skills/`. Edit them there — never edit the copy inside this package, which is created on demand by `prepack`.
+The four skill directories live at the repo root under `skills/`. Edit them there — never edit the copy inside this package, which is created on demand by `prepack`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ara-commons/ara-skills",
-  "version": "0.3.0",
-  "description": "Install Agent-Native Research Artifact (ARA) skills — compiler, research-manager, rigor-reviewer — into Claude Code, Cursor, OpenCode, Gemini CLI, Codex, and more.",
+  "version": "0.4.0",
+  "description": "Install Agent-Native Research Artifact (ARA) skills — compiler, research-manager, rigor-reviewer, research-visualizer — into Claude Code, Cursor, OpenCode, Gemini CLI, Codex, and more.",
   "type": "module",
   "bin": {
     "ara-skills": "./bin/cli.js"
@@ -33,6 +33,7 @@
     "compiler",
     "research-manager",
     "rigor-reviewer",
+    "research-visualizer",
     "llm",
     "cli"
   ],

package/skills/compiler/SKILL.md

@@ -120,11 +120,26 @@ For non-trivial figures (dense plots, log axes, multi-panel, anything needing re
 **Stage 2 — Cognitive Mapping**
 Map the atoms into `/logic/`:
 - **problem.md**: observations (with numbers) → gaps → key insight → assumptions
-- **claims.md**: falsifiable claims with proof pointers to experiment IDs (E01, E02…). Phrase each
-  `Statement` at the strongest level the cited evidence directly supports; keep raw support in
-  `Evidence basis` and broader synthesis in `Interpretation`. Don't upgrade a validation-metric
-  result into a claim about training dynamics without training-side evidence.
-  **Ground every load-bearing number in a `Statement` like code** (the `# Grounding` discipline,
+- **claims.md**: falsifiable claims with proof pointers to experiment IDs (E01, E02…). A claim's job
+  is the **takeaway, not the record**. Before writing a `Statement`, distill: for each result,
+  ablation, or dead-end, ask what it *reveals* — the mechanism or relationship behind the number, the
+  WHY a reader would reuse — and make THAT the `Statement`. Look across results too, not one at a
+  time: where several experiments together reveal a relationship none shows alone — whether they
+  agree on it or differ in a way that reveals what bounds it — make THAT relationship the claim
+  (`Proof` spanning them, `Dependencies` the narrower claims it rests on), rather than settling for
+  one claim per experiment. The recipe name, run IDs, and numbers are
+  the evidence *for* the takeaway, not the takeaway itself: they live in `Evidence basis`/`Proof`,
+  referenced and never restated in the Statement. A `Statement`'s subject is a mechanism/relationship,
+  never a named recipe/config/run, and carries no run numbers, scores, step counts, or p-values. Bound
+  every Statement with a `Conditions` field (the regime + the untested boundary) and a substantive
+  `Falsification criteria` (about the system for a mechanism claim, about the benchmark's behavior for
+  a methodological one) — this accountability, not a narrowed sentence, is what keeps a generalized
+  claim honest. Don't upgrade a validation-metric result into a claim about training dynamics without
+  training-side evidence. Stating the mechanism a result reveals is the goal **even from a single
+  instance** — what you must NOT do is extrapolate it into a universal law beyond its regime, or
+  assert a distinction the design cannot disentangle; that limit goes in `Conditions` so the
+  `Statement` can still carry the mechanism rather than collapsing back to a recipe-and-number.
+  **Ground every load-bearing number in a claim like code** (the `# Grounding` discipline,
   applied to numbers): before writing it, open its source and copy the matched line verbatim into a
   `**Sources**` entry — `<value> ← <source ref> «matched line» [input]` for values that were set
   (cite where they're defined), `[result]` for values a run produced (cite the log/output that
@@ -135,7 +150,10 @@ Map the atoms into `/logic/`:
 - **concepts.md**: the paper's genuine technical terms, formally defined
 - **experiments.md**: declarative verification/analysis plans (NO exact numbers — directional
   only). "Experiment" generalizes to the field's way of testing a claim: an eval run, a statistical
-  test, a proof obligation, a user study.
+  test, a proof obligation, a user study. Link each experiment to where its results are filed
+  (`Evidence`) and to what produced it (`Run`, including failed/ablated runs). Claims and experiments
+  are many-to-many — a claim that generalises across runs lists every experiment in its `Proof`;
+  don't mirror one experiment per claim.
 - **solution/**: the method layer — `constraints.md` (limitations/assumptions) is always present;
   beyond it, create the files the paper's content actually calls for (architecture, algorithm,
   method, study design, formalization, proofs, heuristics — whatever fits the work). You decide
@@ -152,8 +170,11 @@ whichever layer fits best, preserving the source's granularity. Never silently d
 or released form, *distinct from the prose that describes it*. `src/environment.md` is always
 required (reproducibility). Beyond it, one rule decides everything:
 
-> **Capture every concrete artifact the source actually contains, in its native form; never
-> re-encode a prose-only description as code.**
+> **Represent every concrete artifact losslessly. When it persists in a linkable external store (a
+> run database, a released/versioned repo), point to it — a comprehensive `src/artifacts.md` index,
+> one link per artifact (every run, config, log, script), nothing aggregated or copied. Capture it
+> into `src/execution/` only when it would otherwise be lost — code that lives solely inside the
+> paper, or a source not externally persisted. Never re-encode a prose-only description as code.**
 
 A concrete artifact is real content the cognitive layer doesn't already hold — capture it (grounded
 in the real repo/files when provided), in whatever directory fits. But a method conveyed only in
@@ -178,6 +199,28 @@ the source actually reveals — but the node count and types are **source-bounde
 never invent a dead end, decision, or experiment to hit a number. A paper that hides its failures
 yields a smaller, honest tree (Rule 9 wins).
 
+**Optional per-node changed-code (enrichment for the Research Visualizer).** When the work is a
+sequence of code edits and the scripts are resolvable at compile time, you MAY attach to an experiment
+node the **unified diff** it represents — never required, omitted when unclear:
+1. **Resolve node → representative variant — this link does NOT already exist; construct it.** From the
+   node's `source_refs` / its claims' cited `record_configs` → the run index (`runs.csv`/`runs.jsonl`)
+   row(s) whose family+purpose+bin match → the representative submitted script. Where this is empty or
+   ambiguous (most `decision`/`dead_end` nodes, or evidence that is only journal prose), **omit
+   `code_change`** — never guess a script.
+2. **Resolve node → diff base** from the lineage you already reconstruct for `solution/*` (wave baseline
+   or immediate-parent variant).
+3. **Index both scripts in `src/artifacts.md` under a stable anchor** (`A01`, `A02`, …) carrying real
+   path + sha256 + original location; compute the unified diff (variant vs base) and write it to a tracked
+   **`evidence/changes/<node-id>.diff.md`** sidecar (fenced ```diff, `**Source**` header citing the two
+   anchor ids). Set the node's `code_change: {base_artifact, variant_artifact, lang, diff_file}`. The whole
+   scripts stay pointers (Rule 14) — the diff is a derived, grounded view, like a `derived_subset` table.
+4. **Store-absent ⇒ pointers, not a diff.** If the scripts don't resolve on disk (git-ignored store),
+   still record `code_change` with the anchor ids + a `note`, omit `diff_file` — the visualizer shows a
+   pointer chip. Expected, not a failure.
+
+You MAY also attach `node.thinking` — the agent's deliberation — but **only verbatim** grounded
+journal/decision text; never compose new prose. No verbatim rationale ⇒ leave it absent.
+
 ### Step 3: Generate Files
 
 Write the mandatory core, then the additional files the paper warrants. See
@@ -218,7 +261,7 @@ Run ARA Seal Level 1. Check:
 - Mandatory-core dirs exist (`logic/`, `logic/solution/`, `src/`, `trace/`, `evidence/`) and all
   mandatory-core files exist and are non-empty
 - PAPER.md has valid frontmatter (title, authors, year) + a Layer Index
-- claims.md has C01+ blocks with Statement, Status, Falsification criteria, Proof
+- claims.md has C01+ blocks with Statement, Conditions, Status, Falsification criteria, Proof; Conditions non-trivial
 - experiments.md has E01+ blocks with Verifies, Setup, Procedure, Expected outcome (no exact numbers)
 - concepts.md, related_work.md, constraints.md non-trivial; any heuristics blocks have Rationale,
   Sensitivity, Bounds
@@ -228,6 +271,10 @@ Run ARA Seal Level 1. Check:
   heuristic `Code ref` → a real `src/execution/` file (when both exist); tree `evidence:` → claim IDs
 - Evidence: **every numbered table and figure is filed with BOTH a markdown file and a screenshot
   (.png)**; numbered objects not filed are accounted for in `evidence/README.md` with a reason
+- **Changed-code (only if emitted):** each `evidence/changes/<node>.diff.md` cites two `src/artifacts.md`
+  anchors (`base`/`variant`) that resolve; the diff is verbatim; the node's `code_change` points at the
+  sidecar via `diff_file` (or carries a `note` with no `diff_file` when the store was absent). Optional —
+  absent is fine; never invent a diff or a node→script mapping
 - Evidence files have **Source** fields; figures declare Figure type / Extraction method / Reading
   confidence; estimated readings marked `≈` (not `exact_from_labels`); diagrams/qualitative samples
   carry a visual description, not a fabricated table
@@ -235,6 +282,11 @@ Run ARA Seal Level 1. Check:
 - **Cited locations verified** (Rule 15): every repo path/`file:line` exists and is in range;
   spot-check that trace `source_refs` and evidence `Source` actually contain the cited content; no
   repo fact transcribed from the paper without checking the real file
+- **Statement is a takeaway, not a record** — its own dedicated FAIL pass, symmetric to the
+  number-sources pass: scan EVERY claim's `Statement`. It FAILS if the Statement's subject is a named
+  recipe/config/run, or if the Statement contains a run number, n-count, score, step/bin count, or
+  p-value. Such a claim is a leaderboard coordinate, not knowledge — the mechanism it reveals must
+  become the Statement and the numbers move to `Evidence basis`/`Proof`. Exhaustive, not spot-checked
 - **Number sources bound** (claims & heuristics) — run this as its own dedicated pass, one job: for
   *each* `**Sources**` entry, re-open the cited `file:line` (or trace `node:field`) and confirm the
   verbatim «quote» is actually there and the number in the `Statement`/`Rationale` matches the value
@@ -266,11 +318,11 @@ key stats (claims, experiments, concepts, tree nodes, evidence tables/figures).
 7. **"Not specified"**: if information is genuinely unavailable, write "Not specified in paper" — never guess
 8. **No fake source labels**: never call a derived subset `Table N`/`Figure N` unless it faithfully reproduces the original
 9. **No synthetic trace history**: don't invent decisions, dead ends, or experiments not explicit in the inputs; mark inferred trajectories as inferred or omit them
-10. **Evidence-limited wording**: don't use stronger language than the evidence supports; separate observation from interpretation
+10. **Distill the takeaway, then bound it**: a `Statement` is the mechanism or relationship a result reveals — the reusable WHY — with the named recipe and its numbers demoted to `Evidence basis`/`Proof`, never restated in the sentence and never its subject. Keep it accountable by an explicit `Conditions` regime, a substantive `Falsification criteria` (about the system, or about the benchmark's behavior for a methodological claim), and grounded `Proof` — not by narrowing the sentence to a measured value. A single instance still licenses a mechanism `Statement`: what is forbidden is extrapolating it into a universal law beyond its regime, or asserting a distinction the design cannot disentangle — those limits go in `Conditions`, they do not shrink the Statement back to a recipe-and-number. Still separate observation from interpretation: the numbers stay in the evidence layer, reached via `Proof`/`Evidence basis`
 11. **Visual extraction is honest extraction**: read figures by looking; mark estimates `≈` with extraction method + confidence; never present a digitized estimate as exact, invent points for an unreadable figure, or turn a diagram into a fake data table
 12. **Complete, ordered evidence**: file EVERY numbered table and figure, in order — a systematic sweep, not a lucky sample — each as a markdown transcription PLUS a saved screenshot (`.png`). No early stopping; account for any object you don't file
 13. **Fit the file set to the paper, not the paper to a template**: only PAPER.md + the mandatory core are required. Beyond them, generate the files THIS work actually warrants and nothing it doesn't have. Never force inappropriate files (e.g. model-training configs onto an eval or theory paper)
-14. **`src/` holds concrete artifacts, not re-encoded prose**: capture every concrete artifact the source actually contains, in its native form, grounded in real files. Three sides: (a) never fabricate a code stub from a prose-only method — it already lives in `logic/`, so a `.py` just duplicates it; (b) never drop a concrete artifact that does exist — a lone `environment.md` is wrong when the work has one; (c) when the input provides a repo or code directory, every real runnable source file is **captured into `src/execution/`** in its native form (any language; `# Grounding: transcribed`, cite repo path) — NOT reduced to a pointer in `artifacts.md`. `artifacts.md` is only for deliverables with no capturable source (released binaries, natural-language skill/spec docs, datasets referenced by location), never a shortcut to avoid copying code that exists. No code in the input → (c) does not apply.
+14. **`src/` holds concrete artifacts, not re-encoded prose**: capture every concrete artifact the source actually contains, in its native form, grounded in real files. Three sides: (a) never fabricate a code stub from a prose-only method — it already lives in `logic/`, so a `.py` just duplicates it; (b) never drop a concrete artifact that does exist — a lone `environment.md` is wrong when the work has one; (c) when the work's artifacts **persist in a linkable external store** (a run database, a released or versioned repo), represent them as a **comprehensive pointer index** in `src/artifacts.md` — one link per artifact (every run, config, log, script), nothing aggregated into a vague bucket, nothing copied; a lossy subset-copy is the failure. **Transcribe real source into `src/execution/` only when it would otherwise be lost** — code that lives solely inside the paper, or a source not externally persisted (then `# Grounding: transcribed`, cite path). No implementation in the input → neither applies.
 15. **Source-bounded minimums**: any count or required field is a target, never a license to invent. If the source supports fewer, produce what is real and note the shortfall; for an unstated field write "Not specified in paper" rather than guessing
 16. **Cite by verification, and ask on conflict**: a source reference (evidence `Source`, trace `source_refs`, claim `Proof`, a repo `file:line`/path) promises the cited location actually contains the claim — open it and confirm. Never transcribe a *description* of an artifact as a verified fact about it. **When the code repo and the paper disagree on a fact (line count, path, value, behavior), do NOT pick one silently — surface the conflict to the user and ask which source to follow.** If unverifiable and the user is unavailable, attribute it ("per §X") or omit. Carry a statistic's scope/denominator in its `Source`. **This extends to every load-bearing number in a claim/heuristic `Statement`/`Rationale`: it carries a `**Sources**` entry whose verbatim «quote» you opened and confirmed contains that value — a memory-filled value or a bare path is fabrication; use `[pending]` when you cannot open the source**
 

package/skills/compiler/references/ara-schema.md

@@ -32,6 +32,7 @@ evidence/
   tables/                           # ✓ every numbered Table: tableN.md + tableN.png
   figures/                          # ✓ every numbered Figure: figureN.md + figureN.png
   proofs/                           # as warranted: derivations / proofs
+  changes/                          # as warranted: per-node code-change unified diffs (Research Visualizer)
 rubric/requirements.md              # (Only if a rubric is provided)
 ```
 
@@ -159,20 +160,51 @@ Rule: if a filename includes a source label such as `table3` or `figure4`, it sh
 
 Each claim MUST have ALL fields:
 ```markdown
-## C{NN}: {Short title}
-- **Statement**: {Precise, falsifiable assertion}
+## C{NN}: {generalized title — the takeaway, not a recipe/result name}
+- **Statement**: {the generalized, mechanistic conclusion the evidence supports; subject = a mechanism/relationship, never a named recipe; carries NO run numbers}
+- **Conditions**: {under what conditions it holds; the regime; the known untested boundary}
 - **Status**: {hypothesis|supported|refuted}
-- **Falsification criteria**: {What would disprove this}
+- **Falsification criteria**: {a concrete observation that would disprove it — for a mechanism claim, about the system/world; for a methodological/regime claim, about the benchmark's behavior. Not a tautology or a re-run of the same gate}
 - **Proof**: [{experiment IDs: E01, E02}]
-- **Evidence basis**: {What the cited evidence directly shows}
-- **Interpretation**: {Optional broader reading that should not be confused with the raw evidence}
-- **Dependencies**: {other claim IDs, if any}
+- **Evidence basis**: {what the cited evidence shows — point to it; do NOT restate run numbers in the Statement}
+- **Dependencies**: {claim IDs this one rests on — the narrower claims a more general claim draws on, or a claim it corrects/refines; not mere shared setup; omit if it rests only on its own evidence}
 - **Tags**: {comma-separated keywords}
 ```
 
 Proof MUST reference experiment IDs from experiments.md.
 Each proofed experiment should in turn be backed by evidence files whose rows or measurements actually match the claim being asserted.
-`Statement` should stay at the strongest level directly supported by the cited evidence. Use `Interpretation` for broader synthesis.
+`Statement` is the **generalized conclusion the evidence supports** — a mechanism or relationship,
+not a restatement of run numbers. The claim is kept falsifiable and honest by `Conditions` (the
+regime it holds in + the untested boundary) and a `Falsification criteria`, not by narrowing the
+sentence to a single measured value. Numbers (n, scores, step counts, run IDs) live in the evidence
+layer and are reached via `Proof`/`Evidence basis`, never pasted into `Statement`. `Conditions` is
+mandatory: a generalized Statement with no Conditions is an unbounded slogan.
+
+**Distill the mechanism; bound the reach.** Before writing a `Statement`, ask what the result
+*reveals* — the mechanism or relationship a reader would reuse — and state that; the recipe and its
+numbers are the evidence for it, not the claim, and never its subject. A single instance still
+licenses a mechanism `Statement`; what is forbidden is extrapolating it into a universal law beyond
+its regime, or asserting a distinction the design cannot disentangle. Put that boundary in
+`Conditions` — it bounds *where* the claim holds and is not a license for the verb to over-reach.
+`Conditions` carries the limits so the `Statement` can carry the mechanism.
+
+**A claim's evidence may be one result or several read together.** Most claims distill what a single
+result reveals; but where several experiments together reveal a relationship none shows alone —
+whether they agree on it, or differ in a way that itself reveals what bounds or explains the
+difference — that relationship is the claim. Write it as an ordinary `## C` block whose `Proof` lists
+every experiment it draws on and whose `Dependencies` names the narrower claims it rests on; the same
+distill-the-mechanism, bound-the-reach discipline applies. State the most general relationship the
+evidence supports — bounded by `Conditions`, never asserted past what those experiments jointly show —
+rather than settling for one claim per experiment. A claim need not be about the object under study:
+a reusable relationship the work itself exposes, including in how it was run, is worth a claim.
+
+**The attribution trap (the most common miss).** An ablation / leave-one-out that shows *which*
+components dominate is the *evidence*, not the claim. A Statement that merely names the load-bearing
+vs decorative components passes the no-numbers gate but is still a league table of *this* system.
+Apply the **name-deletion test**: strike your system's component names from the Statement — if
+nothing a stranger working on a different stack could reuse survives, you wrote attribution. State
+instead what the ranking reveals about the *class* of system; the named components and their deltas
+live in `Evidence basis`, reached via `Proof`.
 
 ---
 
@@ -192,11 +224,15 @@ borrowed terms to reach 5 (Rule 14). One section per concept:
 
 ## logic/experiments.md
 
-≥3 experiments. Declarative plans, NOT scripts. NO exact numerical results.
+≥3 experiments. Declarative plans, NOT scripts. NO exact numerical results. Experiments and claims
+are **many-to-many**: one experiment may verify several claims, and a claim that generalises across
+runs lists every experiment it draws on in its `Proof` — do not force a 1:1 claim↔experiment ledger.
 
 ```markdown
 ## E{NN}: {Short title}
-- **Verifies**: {claim IDs, e.g., C01, C02}
+- **Verifies**: {claim IDs this run bears on — may be several}
+- **Evidence**: {evidence file(s) where this run's results are recorded — `evidence/…`; "pending" if not yet filed}
+- **Run**: {what produced this result — a `src/execution/` file (or other `src/` artifact) when captured, else a link/ref into the source repo or run database; give it for EVERY experiment, including failed or ablated runs}
 - **Setup**:
   - Model: {model name and size}
   - Hardware: {GPU type, count, memory}
@@ -286,12 +322,20 @@ field format:
 
 ## src/execution/{module}.py  (when the work warrants it — grounded or absent)
 
-Present only when the source provides **concrete code-shaped content**: actual repo code, or
-explicit pseudocode/equations the paper prints. When a repo is provided, capture its real runnable
-source files here in native form (transcribed) — not merely a stub of the novel mechanism; when only
-pseudocode/equations exist, the reconstructed stub captures the **novel mechanism**. Either way it
+Capture here is the **fallback, not the default**: transcribe code into `src/execution/` only when it
+would otherwise be **lost** — it exists solely inside the paper, or its source is not externally
+persisted. When the work's code/runs **persist in a linkable external store** (a repo, a run
+database), do NOT copy them here — index them comprehensively in `src/artifacts.md` (see below). When
+capture IS the call: actual repo code → capture real runnable files in native form (transcribed); only
+pseudocode/equations the paper prints → a reconstructed stub of the **novel mechanism**. Either way it
 must be grounded — never fabricated.
 
+When the input is a run database / repo of many experiment runs, index it **comprehensively** in
+`src/artifacts.md`: a link for **every** run and artifact (the per-run logs — e.g. a `runs.jsonl`
+already indexes each — plus every config, candidate, log, and script), nothing aggregated into a vague
+bucket and nothing copied. Each experiment's `Run` field points at the relevant entries. A lossy
+subset — only the winning run, or runs collapsed into a single directory link — is the failure.
+
 Every file declares its grounding on the first line:
 ```python
 # Grounding: transcribed   — adapted from repo code; cite file:line in docstrings
@@ -320,20 +364,23 @@ pseudo-code — that information already lives in `logic/solution/`, and re-enco
 duplicates it.** A concrete artifact that IS raw "code" — e.g. a prompt or template — is different:
 store it verbatim in `src/prompts/`, don't paraphrase it. A hollow invented API is a hallucination.
 
-## src/artifacts.md  (for non-code deliverables — NOT a substitute for capturing real source)
+## src/artifacts.md  (the artifact index — comprehensive pointer file when the source persists externally)
 
-`src/` must still represent the implementation. When the deliverable is a released tool, library,
-skill/specification, system, benchmark, or dataset rather than a code stub, describe the **real**
-artifacts here — grounded in the actual repo/files when a repo is provided. One block per artifact:
+`src/` must represent the implementation **losslessly**. When the work's artifacts **persist in a
+linkable external store** (a repo, a run database, a released tool/dataset), `artifacts.md` is the
+**comprehensive pointer index** — a link to **every** artifact (every run, config, log, script,
+released binary, dataset), grounded in the real files, nothing aggregated into a vague bucket and
+nothing copied. One block (or row) per artifact:
 
-**Exception — actual source code is captured, not pointed at.** When the repo contains real runnable
-source files, copy those files into `src/execution/` in native form (`# Grounding: transcribed`,
-cite path); do not reduce them to a prose block here. `artifacts.md` covers only deliverables with
-no capturable source — released binaries, natural-language skill/spec docs, datasets referenced by
-location. Naming a real `.py`/`.js`/… file here instead of capturing it is a coverage failure.
+**Capture is the fallback, not the default.** Transcribe a file into `src/execution/` only when it
+would otherwise be **lost** — code that lives solely inside the paper, or a source not externally
+persisted. When the source persists and is linkable, point to it here; copying a lossy subset (only
+the winner, or files collapsed into a single directory link) is the failure.
 
 ```markdown
 ## {Artifact name}
+- **Anchor**: {stable short id — `A01`, `A02`, … — so a trace node's `code_change` can reference this artifact by id; optional, but required for the Research Visualizer's changed-code diffs}
+- **sha256**: {content hash of the file, when a code-change diff cites it}
 - **File(s) in repo**: {real path(s), verified to exist}
 - **Nature**: {what it is — tool / library / skill spec / system / dataset}
 - **What it does / contains**: {grounded description}
@@ -379,6 +426,28 @@ Reproducibility for any field. For purely analytical work, state so explicitly.
 
 ---
 
+## evidence/changes/{node-id}.diff.md  (Research Visualizer changed-code diffs)
+
+Per-experiment-node **unified diff** the step represents — a derived, grounded view (the whole scripts
+stay pointers in `src/artifacts.md`; this is NOT a copy of the artifact). One tracked file per node that
+has a resolvable code change:
+
+```markdown
+# Change {node-id}: {short description}
+- **Base**: A01   (→ src/artifacts.md anchor; path + sha256 + original location live there)
+- **Variant**: A07
+- **Language**: python
+
+<unified diff fenced as ```diff … ``` — verbatim from the real scripts>
+```
+
+Rules: cite the two artifacts **by anchor id**, never paste their paths/sha here (those live once in
+`src/artifacts.md`). The diff text is verbatim. If the scripts can't be resolved at compile time
+(git-ignored store), omit this file and set the node's `code_change.note` instead (the visualizer shows a
+pointer chip, no diff). These sidecars MUST be tracked/committed (not swept by any store `.gitignore`).
+
+---
+
 ## evidence/tables/{file}.md (+ screenshot)
 
 Every numbered table gets BOTH this markdown file AND a screenshot `tableN.png` (the rendered
@@ -431,6 +500,9 @@ tree:
     source_refs: ["Table 2", "§4.1"]   # recommended for explicit nodes
     title: "{...}"
     description: "{...}"
+    # OPTIONAL enrichment (Research Visualizer; omit when absent):
+    # thinking: "{verbatim agent deliberation — why it did/branched}"
+    # code_change: { base_artifact: A01, variant_artifact: A07, lang: python, diff_file: evidence/changes/N01.diff.md }
 ```
 
 Rules:

package/skills/compiler/references/validation-checklist.md

@@ -35,14 +35,15 @@ where present, they are non-trivial — there is no fixed list. Model-training f
 
 ### logic/claims.md
 - Has `## C\d+` blocks (at least one claim)
-- Contains `**Statement**`
-- Contains `**Sources**`; every load-bearing number in a `Statement` has a `Sources` entry carrying
+- Contains `**Statement**` (the mechanism/takeaway a result reveals — subject is a mechanism/relationship, never a named recipe; no run numbers)
+- Contains `**Conditions**` (non-trivial: the regime + the untested boundary)
+- Contains `**Sources**`; every load-bearing number in a claim has a `Sources` entry carrying
   a verbatim «quote» plus an `[input]`/`[result]` tag — no bare-path entries, no memory-filled numbers
 - Contains `**Status**`
-- Contains `**Falsification criteria**`
+- Contains `**Falsification criteria**` (a substantive observation — about the system, or about the benchmark's behavior for a methodological claim — not a tautology or a re-run of a metric gate)
+- `Statement` is the mechanism/takeaway a result reveals, not a record: a single instance may state the mechanism it reveals, but must not be extrapolated into a universal law beyond its regime, nor assert a distinction the design cannot disentangle — those limits live in `Conditions`
 - Contains `**Proof**`
 - Contains `**Evidence basis**`
-- Contains `**Interpretation**`
 
 ### logic/problem.md
 - Has `### O\d+` blocks (observations)
@@ -52,6 +53,8 @@ where present, they are non-trivial — there is no fixed list. Model-training f
 ### logic/experiments.md
 - Has `## E\d+` blocks (at least 3)
 - Contains `**Verifies**`
+- Contains `**Evidence**` (link to where the run's results are filed, or "pending")
+- Contains `**Run**` (what produced the run — a `src/execution/` file or a link/ref into the source repo/DB; failed/ablated runs are linked too, not omitted)
 - Contains `**Setup**`
 - Contains `**Procedure**`
 - Contains `**Expected outcome**` or `**Expected results**`
@@ -89,9 +92,10 @@ fewer passes with fewer; what fails is fabricated filler.
 - `src/execution/`: ≥1 `.py` file only when the work has implementable content (repo code / paper pseudocode / named interface). NOT mandatory otherwise; omitting it (with a note in `environment.md`) beats fabricating one.
 - `evidence/tables/`, `evidence/figures/`, or `evidence/proofs/`: contains the filed evidence (see §11)
 
-### Implementation layer (`src/`) — captured, not re-encoded
-- Concrete artifacts that exist are captured in native form: prompts/templates verbatim in `src/prompts/`, **real repo source code captured into `src/execution/`** (native form, `# Grounding: transcribed`, cite path — not reduced to a pointer), non-code deliverables (released binaries, skill/spec docs, referenced datasets) described in `src/artifacts.md`, config values in `src/configs/`. A lone `environment.md` is wrong when such artifacts exist.
-- **When a code repo/directory was provided as input**: every non-trivial runnable source file in it (a named module, entrypoint, or roughly ≥30 lines) is captured into `src/execution/` (or another `src/` subdir, in native form), not merely named in `artifacts.md`. FAIL on real source code represented only by a pointer, or a set of real files dismissed collectively (e.g. "not a core contribution") without capture.
+### Implementation layer (`src/`) — indexed when external, captured when it'd be lost
+- Concrete artifacts are represented losslessly: prompts/templates verbatim in `src/prompts/`, config values in `src/configs/`, and — when the work's code/runs **persist in a linkable external store** — a **comprehensive pointer index** in `src/artifacts.md` linking every artifact. A lone `environment.md` is wrong when such artifacts exist.
+- **Comprehensiveness** (external repo/run-database input): `src/artifacts.md` links **every** run and source file (per-run logs included — a `runs.jsonl` counts), nothing aggregated into a bare directory link or a "~N others" summary. FAIL on a lossy subset (only the winning run; real artifacts collapsed into a vague bucket).
+- **Capture only when it'd be lost**: transcribe source into `src/execution/` (native form, `# Grounding: transcribed`, cite path) only when it exists solely inside the paper or its source is not externally persisted. Pointer-only is correct when the source persists; it FAILS only when the pointer would dangle (no persisted source).
 - Conversely, a prose-only method (no code, no prompt, no config values) is NOT re-encoded as a `.py` stub or pseudo-code — it lives in `logic/solution/`; a lone `environment.md` is correct here. FAIL on a `.py` stub manufactured from prose (it just duplicates the cognitive layer).
 
 ### Code grounding (each `src/execution/*.py`, when present)
@@ -150,11 +154,18 @@ For each file in `evidence/figures/*.md` specifically:
 ### Claim Proof → Experiment Resolution
 - Every `E\d+` in a claim's `**Proof**: [...]` must exist in experiments.md
 - Proof-linked experiments should have evidence files whose labels and row contents actually match the compared systems or measurements
-- Claim wording should be auditable against `Evidence basis`; broader language should be isolated to `Interpretation`
+- Claim `Statement` is a generalized mechanism/relationship auditable against `Evidence basis`; its reach is bounded by `Conditions` and its run numbers live in the evidence layer (not pasted into the Statement)
 
 ### Experiment Verifies → Claim Resolution
 - Every `C\d+` in an experiment's `**Verifies**` must exist in claims.md
 
+### Experiment Evidence / Run → Resolution
+- Every `evidence/…` path in an experiment's `**Evidence**` is a filed evidence file (or "pending")
+- Every experiment carries a `**Run**` ref — an entry in the comprehensive `src/artifacts.md` index (or, in the capture-fallback case, a `src/execution/` file) that links the source location; failed/ablated runs are linked there, not dropped
+
+### Claim Dependencies → Claim Resolution
+- Every `C\d+` in a claim's `**Dependencies**` must exist in claims.md (an unresolved ID FAILS)
+
 ### Heuristic Code Ref → File Resolution (only when heuristics.md + src/execution/ are both present)
 - Every `src/...` path in `**Code ref**: [...]` must be an existing file
 
@@ -174,6 +185,19 @@ For each file in `evidence/figures/*.md` specifically:
 - No fact ABOUT a repo artifact (line count, path, internal structure) is transcribed from the paper without checking the real file — when paper and repo disagree, the discrepancy is flagged, not silently resolved to the paper's number
 - Spot-check trace `source_refs` and evidence `**Source**` labels: the cited section/table/appendix actually contains the claimed content
 - A statistic carries its scope/denominator (N, population) in its `Source` — subset figures (e.g. "5 papers / 3,050 reqs") are not juxtaposed with full-corpus figures as if same-denominator
+- **Claim Statements are takeaways** (exhaustive, not spot-checked — symmetric to the number-sources
+  pass): each `## C\d+` Statement FAILS if its subject is a named recipe/config/run, or if it
+  contains a run number, n-count, score, step/bin count, or p-value. The mechanism a result reveals
+  must be the subject; the numbers must live in `Evidence basis`/`Proof`
+- **Attribution is not insight** (exhaustive, applied to each Statement that already passed the
+  takeaways gate above): a Statement also FAILS if it only identifies *which* named components of
+  this one system rank highest/lowest (load-bearing / dominant / decorative / inert / "largest
+  contributor") without stating what that ranking *reveals* — a relationship or mechanism a reader
+  could carry to a different system. **Operational tell: delete this system's component names from
+  the Statement; if no transferable relationship survives, it is attribution, not a mechanism — it
+  FAILS.** The fix is to state the generalization the ranking licenses; the named components and
+  their deltas stay in `Evidence basis`. This is the most common way a numerically-clean Statement
+  still fails the insight bar.
 - **Claim/heuristic number sources** (exhaustive, not spot-checked): each `**Sources**` entry's cited
   `file:line` (or trace `node:field`) exists, the verbatim «quote» is actually present there, and the
   number in the `Statement`/`Rationale` matches the value inside that quote; `[input]` entries cite

package/skills/research-manager/SKILL.md

@@ -15,7 +15,7 @@ argument-hint: "[optional: hint about what happened this turn]"
 allowed-tools: Read, Write, Edit, Glob, Grep
 metadata:
   author: ara-commons
-  version: "2.3.0"
+  version: "2.4.0"
   tags: [research, process-recording, provenance, progressive-crystallization, knowledge-management]
 ---
 
@@ -184,10 +184,17 @@ entries — staged observations belong to Stage 3. (History lives in the trace;
 1. **Status updates** — flip a claim's `Status` field when evidence warrants.
 2. **Content revisions** — rewrite a `Statement`, `Rationale`, or definition when new
    evidence narrows scope, terminology changed, or wording no longer matches what's
-   actually supported. A rewrite re-grounds every number it now contains (Number grounding);
+   actually supported. Keep `Statement` a generalized mechanism/relationship and sharpen
+   `Conditions` as the regime becomes clearer; new run numbers update `Proof`/`evidence`,
+   never the Statement. A rewrite re-grounds every number it now contains (Number grounding);
    any changed value gets its own fresh `Sources` «quote», never a carried-over one.
 3. **Structural changes** — split a claim into two, merge duplicates, repair
-   dependencies, rename ids when concepts are renamed.
+   dependencies, rename ids when concepts are renamed. Also **generalize**: when several
+   crystallized claims are together evidence for a more general relationship none states
+   alone, author a new claim whose `Dependencies` are those narrower claims and whose
+   `Proof` spans their evidence — keep the narrower claims in place; the new claim sits
+   above them, not instead of them (only when a signal this turn makes the relationship
+   evident — never a routine sweep).
 4. **Consistency pass** — scan for broken cross-references (claim cites C05 which no
    longer exists), terminology mismatch with `concepts.md`, dependency loops.
 
@@ -257,6 +264,8 @@ When a signal fires for entry `E` (claim, heuristic, or concept):
      new id for the spin-off, update all cross-references.
    - **Merge**: keep the lower id, mark the higher id as `withdrawn` with
      `Merged into: C{XX}`, redirect cross-references.
+   - **Generalize**: allocate a new id for the more general claim, set its `Dependencies`
+     to the narrower claims, and leave those claims in place (they remain its grounding).
 6. **Record full before/after in today's session record** under `logic_revisions:`
    (see schema below). This is the ONLY place the prior wording is preserved — the
    logic file does not keep it.
@@ -361,18 +370,34 @@ tree:
 ### Claim (`logic/claims.md`) — crystallized only
 
 ```markdown
-## C{XX}: {title}
-- **Statement**: {current falsifiable assertion}
-- **Sources**: [{one entry per load-bearing number in `Statement`: `<value> ← <file:line | trace-node:field> «verbatim line copied from source» [input|result]`, or `<value> ← [pending: reason]`}]   # see "Number grounding"; a bare path with no «quote» is invalid
+## C{XX}: {generalized title — the takeaway, not a recipe name}
+- **Statement**: {the generalized, mechanistic conclusion; subject = a mechanism/relationship, never a named recipe; carries NO run numbers}
+- **Conditions**: {under what conditions it holds; the regime; the known untested boundary}
+- **Sources**: [{one entry per load-bearing number in the claim (now in `Conditions`/`Proof`): `<value> ← <file:line | trace-node:field> «verbatim line copied from source» [input|result]`, or `<value> ← [pending: reason]`}]   # see "Number grounding"; a bare path with no «quote» is invalid
 - **Status**: hypothesis | untested | testing | supported | weakened | refuted | withdrawn
 - **Provenance**: user | ai-suggested | user-revised
-- **Falsification criteria**: {what would disprove this}
-- **Proof**: [{evidence refs or "pending"}]
+- **Falsification**: {a concrete observation that would disprove it — for a mechanism claim, about the system/world; for a methodological/regime claim, about the benchmark's behavior. NOT a tautology or a re-run of the same gate ("if the recipe fails the gate")}
+- **Proof**: [{evidence refs (→ evidence/) or "pending"; run numbers/IDs/scores live HERE, not in Statement}]
 - **Dependencies**: [C{YY}, ...]
 - **Tags**: {comma-separated}
 - **Last revised**: YYYY-MM-DD (turn-id)   # pointer back to the trace; absent until first revision
 ```
 
+**The Statement is the generalized conclusion the evidence supports — a mechanism or relationship,
+not a restatement of run numbers.** What keeps it falsifiable and honest is `Conditions` (the regime
+it holds in + the untested boundary) plus a `Falsification`, not a narrowed sentence. Numbers (run
+IDs, n, scores, step counts) belong in `Proof` → `evidence/` (grounded per Number grounding), never
+in `Statement`. `Conditions` is mandatory: a generalized Statement with no Conditions is an unbounded
+slogan.
+
+**Calibrate the Statement to what the evidence actually separates.** Do not assert a distinction the
+design cannot disentangle (confounded factors — e.g. matrix "shape" vs "role" when they co-vary), or
+a law from a single instance. When that's the case, hedge in the Statement itself — name the
+unseparated factors together, or say "shown once here" — rather than only burying it in `Conditions`.
+`Conditions` bounds *where* the claim applies; it is not a license for the Statement's verb to
+over-reach. The Statement/Conditions may be sharpened on a later turn (Stage 4 content revision) as
+the mechanism becomes clearer — no new closure signal is needed.
+
 Current-state snapshot only — no prior statements, no `From staging`/`Crystallized via`
 notes. Crystallization and every edit are recorded in the trace (`trace/sessions/…` under
 `logic_revisions:` with before/after; source observation stays in `staging/`; reasoning in

package/skills/research-manager/references/event-taxonomy.md

@@ -72,7 +72,7 @@ What KIND of event is this?
       → ai-action  [session record only]
 
   Interpretation (something asserted to be true / general)?
-    Falsifiable assertion about the system?
+    Generalizable falsifiable assertion (a mechanism/relationship, bounded by conditions)?
       → STAGE as potential_type: claim
     Implementation rule with rationale?
       → STAGE as potential_type: heuristic