@ara-commons/ara-skills 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ara-commons/ara-skills",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Install Agent-Native Research Artifact (ARA) skills — compiler, research-manager, rigor-reviewer — into Claude Code, Cursor, OpenCode, Gemini CLI, Codex, and more.",
   "type": "module",
   "bin": {
@@ -40,12 +40,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/AmberLJC/Agent-Native-Research-Artifact.git",
+    "url": "https://github.com/ARA-Labs/Agent-Native-Research-Artifact.git",
     "directory": "packages/ara-skills"
   },
-  "homepage": "https://github.com/AmberLJC/Agent-Native-Research-Artifact#readme",
+  "homepage": "https://github.com/ARA-Labs/Agent-Native-Research-Artifact#readme",
   "bugs": {
-    "url": "https://github.com/AmberLJC/Agent-Native-Research-Artifact/issues"
+    "url": "https://github.com/ARA-Labs/Agent-Native-Research-Artifact/issues"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/compiler/SKILL.md

@@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Bash(python *|git clone *|ls *|mkdir *), Glob,
 metadata:
   author: ara-commons
   category: research-tooling
-  version: "1.1.0"
+  version: "1.2.0"
   tags: [research, compilation, artifacts, knowledge-extraction]
 ---
 
@@ -120,14 +120,40 @@ 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.
+- **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
+  reports them). Never write a number from memory and back-fill a path; never carry a value over
+  from a dependency claim — re-open this claim's own source. A bare path with no «quote» is invalid;
+  if a source can't be opened this turn, write `[pending: …]` (an unverified path is fabrication,
+  worse than `[pending]`).
 - **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
@@ -144,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
@@ -210,7 +239,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
@@ -227,6 +256,18 @@ 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
+  inside the quote; `[input]` entries cite recipe scripts, `[result]` entries cite logs/trace (not
+  swapped). Exhaustive, not spot-checked. `[pending: …]` entries are allowed but listed for
+  follow-up; a bare path, a «quote» absent from the cited line, or a value that disagrees with its
+  quote FAILS
 - **Self-consistency**: ARA-authored derived numbers recompute; PAPER.md declared counts match the
   files; tree `evidence:` refs are claim IDs (C##), not observation IDs
 
@@ -251,13 +292,13 @@ 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. Two 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
+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`
+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**
 
 ## Reference Files
 

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

@@ -159,20 +159,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 +223,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,22 +321,41 @@ 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. The stub captures the **novel mechanism** and must
-be grounded — never fabricated.
+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
 # Grounding: reconstructed — from explicit paper pseudocode/equations; cite §/eq
 ```
-Contents:
+Contents depend on the grounding:
+
+**`transcribed` (a real repo file is provided)** — copy it faithfully in native form: full function
+bodies, the file's own imports (third-party deps included), and its real scaffolding (CLI/argparse,
+logging, entrypoints) all kept as in the repo. Do NOT replace working code with
+`NotImplementedError`, strip plumbing, or reduce to signatures-only — that mutates the artifact and
+breaks the cited `file:line`. Add only the `# Grounding` line and source-citing docstrings; otherwise
+leave the file as it is in the repo.
+
+**`reconstructed` (only pseudocode/equations exist)** — build a minimal stub of the novel mechanism:
 - Typed function signatures using ONLY names/types the source states
-- Docstrings that cite the source (`§4.2`, `Eq. 3`, `repo: model.py:88`) — not paraphrases of this skill
+- Docstrings that cite the source (`§4.2`, `Eq. 3`) — not paraphrases of this skill
 - Implementation logic ONLY where the source provides it; everything unspecified stays
   `raise NotImplementedError("Not specified in paper")` — never plausible filler
-- NO scaffolding (no argparse, logging, distributed wrappers)
-- Import only standard libraries + the field's core stack (torch/numpy, pandas/statsmodels, etc.)
+- NO scaffolding (no argparse, logging, distributed wrappers); import only standard libraries + the
+  field's core stack (torch/numpy, pandas/statsmodels, etc.)
 
 Hard rule: do not invent API names, function bodies, constants, or hyperparameters. **If the paper
 describes the method only in prose (no code, no printed pseudocode), do NOT write a `.py` stub or
@@ -309,11 +363,18 @@ 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  (when the implementation is not a `.py` stub)
+## src/artifacts.md  (the artifact index — comprehensive pointer file when the source persists externally)
+
+`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:
 
-`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:
+**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}

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

@@ -35,12 +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 `**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)
@@ -50,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**`
@@ -87,8 +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 code/tools/skills via grounded `src/execution/` or `src/artifacts.md`, config values in `src/configs/`. A lone `environment.md` is wrong when such artifacts exist.
+### 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)
@@ -147,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
 
@@ -171,6 +185,25 @@ 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
+  recipe scripts and `[result]` entries cite run logs/trace (not swapped). A bare path with no «quote»,
+  a «quote» absent from the cited line, or a value that disagrees with its quote FAILS. `[pending: …]`
+  entries pass but are listed for follow-up — an unverified plausible path does not pass
 
 ## 11. Evidence Ledger Completeness
 

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.2.0"
+  version: "2.4.0"
   tags: [research, process-recording, provenance, progressive-crystallization, knowledge-management]
 ---
 
@@ -128,8 +128,10 @@ When a signal fires for `O{XX}`:
 
 1. Read O{XX}'s `content`, `context`, `potential_type`, `provenance`, `bound_to`.
 2. Allocate the next ID for the target layer (read the target file first).
-3. Construct a typed entry using the schema (see Schemas below). Carry forward
-   `provenance`. Verbal-affirmation upgrades `ai-suggested` → `user-revised` (or `user` if
+3. Construct a typed entry using the schema (see Schemas below). **Before any number enters a
+   `Statement`/`Rationale`, ground it per "Number grounding" below — open the source, copy the
+   matched line verbatim into `Sources`, then write the number as a copy of that quote.** Carry
+   forward `provenance`. Verbal-affirmation upgrades `ai-suggested` → `user-revised` (or `user` if
    reproduced verbatim). The other three signals do **not** upgrade provenance.
 4. Add fields: `Crystallized via: <signal>`, `From staging: O{XX}`.
 5. Establish forensic bindings (claim→proof, heuristic→code, decision→evidence). Use
@@ -137,6 +139,24 @@ When a signal fires for `O{XX}`:
 6. Update O{XX}: `promoted: true`, `promoted_to: <layer>:<id>`, `crystallized_via: <signal>`.
    **Do not delete the observation** — the trail from raw to typed is part of the record.
 
+#### Number grounding (claims & heuristics)
+
+Every load-bearing number in a `Statement` (or a heuristic's `Rationale`/`Sensitivity`/`Bounds`)
+is grounded the way code is — transcribed from an open source, never written from memory:
+
+1. **Open before you write.** Before the number enters the prose, open its source and copy the
+   matched line *verbatim* into `Sources` (`<value> ← <source ref> «matched line» [input|result]`).
+   The number you then write in the prose is a copy of the value inside that quote — not a value
+   recalled and back-cited. An entry with a bare path and no «quote» is invalid.
+2. **Input vs result.** Tag each entry `[input]` (a value you set — cite the source that defines it)
+   or `[result]` (a value the run produced — cite the log/output that reports it). Don't cite a
+   measured outcome to the config meant to produce it, or vice versa.
+3. **No inheritance.** Re-open *this* claim's own source for every number; a value shared with a
+   dependency claim is re-verified here, never copied from the dependency's wording.
+4. **`[pending]` beats a guess.** Can't open or locate a source this turn? Write
+   `<value> ← [pending: what's missing]`. An unverified-but-plausible path is fabrication and is
+   worse than `[pending]`.
+
 #### Contradiction trigger
 
 When a new event contradicts something already staged or crystallized:
@@ -164,9 +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.
+   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.
 
@@ -236,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.
@@ -340,17 +370,34 @@ tree:
 ### Claim (`logic/claims.md`) — crystallized only
 
 ```markdown
-## C{XX}: {title}
-- **Statement**: {current falsifiable assertion}
+## 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
@@ -362,6 +409,7 @@ marker, not a resting state — see Stage 4.
 ```markdown
 ## H{XX}: {title}
 - **Rationale**: {current best explanation of why this works}
+- **Sources**: [{one entry per load-bearing number in `Rationale`/`Sensitivity`/`Bounds`, same format as claims — see "Number grounding"}]
 - **Status**: active | weakened | retired
 - **Provenance**: user | ai-suggested | user-revised
 - **Sensitivity**: low | medium | high | unknown   # "unknown" until the turn establishes it — never guess

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

package/skills/rigor-reviewer/SKILL.md

@@ -148,6 +148,7 @@ For each claim's Falsification criteria field:
 
 - **Over-claiming**: Does any Statement use universal scope markers ("all models", "any dataset", "state-of-the-art across all") while cited experiments cover only specific, narrow conditions? The gap must be substantial.
 - **Under-claiming**: Are there important experimental results present in evidence/ that are not captured by any claim? (Evidence without a corresponding claim.)
+- **Attribution vs mechanism**: Does any Statement merely name *which* components of this one system rank highest/lowest (load-bearing, dominant, decorative, inert) without stating what that ranking *reveals*? Apply the name-deletion test — strike the system's component names; if no transferable relationship survives, the Statement is attribution, not insight. Flag as `major` (the claim is a league table of this system, not a reusable finding); suggest the generalization the ranking licenses.
 - **Assumption explicitness**: Are key assumptions stated in problem.md (Assumptions section) or constraints.md? Are there unstated assumptions implied by the experimental design?
 - **Generalization boundaries**: Does the artifact clearly state what the claims do NOT apply to? Check constraints.md and limitations in the exploration tree.
 - **Qualifier consistency**: When claims use hedging ("tends to", "in most cases"), is this consistent with the evidence strength?

package/skills/rigor-reviewer/references/review-dimensions.md

@@ -65,6 +65,7 @@ resolution, field presence, YAML parsing) is handled entirely by Level 1.
 |-------|---------------|-----------------|
 | Over-claiming | Statement uses universal scope while evidence covers narrow conditions | critical if extreme, major if moderate |
 | Under-claiming | Evidence files or experiment results not captured by any claim | minor |
+| Attribution vs mechanism | Statement names which components rank where (name-deletion test leaves nothing transferable) instead of what the ranking reveals | major |
 | Assumption explicitness | Key assumptions stated in problem.md or constraints.md | major if unstated assumptions affect validity |
 | Generalization boundaries | Artifact states what claims do NOT apply to | minor |
 | Qualifier consistency | Hedging language matches evidence strength | minor |

package/src/installer.js

@@ -45,7 +45,7 @@ function writeLock(dir, data) {
   ensureDir(dir);
   fs.writeFileSync(
     file,
-    JSON.stringify({ updatedAt: new Date().toISOString(), ...data }, null, 2)
+    JSON.stringify({ ...data, updatedAt: new Date().toISOString() }, null, 2)
   );
 }