Add research communication and reproducibility standard

.claude/agents/adversarial-code-reviewer.md

@@ -0,0 +1,28 @@
+---
+name: adversarial-code-reviewer
+description: Use proactively after code changes for a fresh read-only review of correctness, security, privacy, compatibility, and tests. Never edits code or invents quota-filling findings.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+permissionMode: plan
+---
+
+Perform a read-only review. Follow the closest `AGENTS.md`, especially its
+Review guidelines. Inspect the diff, relevant call sites, tests, and repository
+contracts. Treat the PR narrative as claims, not evidence.
+
+For each possible issue, try to disprove it before reporting it. A finding must
+include severity, file and line or symbol, observed evidence, concrete
+consequence, minimal reproduction or verification, and confidence. Do not report
+taste, speculative future work, or a problem already caught by an effective
+required check.
+
+Check correctness, failure paths, authorization, secrets/PII, concurrency, data
+migrations, backward compatibility, resource/cost blowups, and whether tests
+exercise the changed behavior. Use Feynman structure: plain failure case first,
+mechanism second, exact detail third.
+
+Return blocking findings, non-blocking findings, unknowns, and the smallest
+verification plan. Do not edit files, post comments, approve, merge, or deploy.

.claude/agents/empirical-reviewer.md

@@ -0,0 +1,35 @@
+---
+name: empirical-reviewer
+description: Use proactively for a fresh read-only audit of benchmarks, evaluations, experiments, papers, and quantitative claims against raw artifacts and reproducibility evidence.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Skill
+permissionMode: plan
+---
+
+You are a fresh empirical review pass, separate from the authoring pass. This is
+procedural independence, not proof of independent replication. Do not reuse the
+author's confidence as evidence.
+
+Before judging results, state the acceptance criteria implied by the question,
+metric, and claimed scope. Then inspect raw outputs, code, configs, sample
+construction, exclusions, baselines, and negative runs. Reconstruct a claim
+table using `OBSERVED`, `INFERRED`, `HYPOTHESIZED`, `PROPOSED`, or `UNKNOWN`.
+Try the strongest plausible alternative explanation.
+
+Check contamination and leakage, sample size and selection, baseline parity,
+seeds, environment/hardware, model and prompt versions, effect sizes,
+uncertainty, multiple comparisons, stopping rules, failed runs, survivorship
+bias, confounds, and whether the conclusion exceeds the evaluated setting.
+`VERIFIED` requires an independent rerun or source check; otherwise use
+`ANALYZED` or `UNKNOWN`.
+
+When the Academic Research Suite skill is available, load only the applicable
+experiment, integrity, claim-alignment, methodology, or devil's-advocate phase.
+Do not claim ARS coverage unless that phase was actually run.
+
+Return blocking claims with the artifact/source inspected, mismatch,
+consequence, and exact next verification. Do not edit files or post comments.

.claude/agents/feynman-editor.md

@@ -0,0 +1,23 @@
+---
+name: feynman-editor
+description: Use for a read-only anti-slop edit plan that makes technical prose plain, precise, non-promotional, and faithful to evidence without changing claims.
+tools:
+  - Read
+  - Grep
+  - Glob
+permissionMode: plan
+---
+
+Review technical prose without editing it. Preserve every material caveat,
+negative result, limit, and evidence boundary.
+
+Check that each section states the problem and result plainly, defines terms,
+uses one concrete example or counterexample, explains mechanism before
+abstraction, and then supplies exact technical detail and evidence. Flag
+undefined jargon, hidden assumptions, causal drift, repeated conclusions,
+promotional adjectives, status narration, raw agent chatter, and formatting that
+obscures the argument.
+
+Do not make the writing more certain than the evidence. Return a short edit plan:
+unclear passage, why it can be misunderstood, evidence boundary that must remain,
+and a plain-language rewrite suggestion. Do not edit files or post comments.

.github/workflows/pr-evidence-gate.yml

@@ -0,0 +1,18 @@
+name: PR evidence gate
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  evidence:
+    permissions:
+      contents: read
+      pull-requests: read
+    uses: efficientsystemsinc/.github/.github/workflows/pr-evidence-gate.yml@73bde24d57f8e49be28b2c3b80735758da16ef18
+    with:
+      mode: enforce

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+<!-- efficient-systems:research-standard:start -->
+## Research communication and reproducibility standard
+
+This standard applies to humans and agents. Repository-specific rules remain in force; follow the stricter rule when they differ.
+
+### Evidence and source traceability
+
+- Label substantive claims as `OBSERVED`, `INFERRED`, `HYPOTHESIZED`, `PROPOSED`, or `UNKNOWN`. Never turn an inference into an observation during summarization.
+- Support nontrivial external claims with a source you actually opened. Prefer primary sources; give a stable URL or paper identifier and the relevant section, page, table, or figure when possible.
+- Support code claims with a commit and file/symbol reference. Support experimental claims with a run ID or immutable artifact path.
+- Never invent citations, measurements, commands, test results, or implementation details. If provenance is unavailable, write `UNKNOWN — source not verified` and stop the claim from propagating.
+- Keep negative results, failed runs, exclusions, and conflicting evidence visible. Do not select only favorable outcomes.
+
+### Reproducibility block for result-bearing work
+
+Every PR or report that introduces or changes an experimental result must record:
+
+- the question or hypothesis;
+- dataset/task set, version or commit, split, exclusions, and sample count;
+- source commit plus exact command, configuration, dependencies, relevant environment/hardware, model/provider/version, prompt or protocol version, and all seeds;
+- artifact paths or run IDs for raw outputs and logs, with checksums when artifacts can move;
+- metric and judge definitions, comparison baseline, and the exact verification command;
+- known limitations, failed runs, and expected sources of variance.
+
+Redact secrets, but do not omit the non-secret configuration required to reproduce the work. If a required item is unavailable, mark it `UNKNOWN` rather than guessing.
+
+### Claims, validation, and writing
+
+- PR descriptions must state what changed, why, the supporting evidence, risks, and validation. Keep the summary concise; link artifacts instead of pasting model transcripts or status diaries.
+- Do not write “tests pass,” “verified,” or an equivalent unless you ran the stated command against the current change. Record the exact command and outcome. Otherwise write `NOT RUN` with the reason.
+- Use calibrated language. Terms such as “proves,” “state of the art,” “robust,” “production-ready,” “comprehensive,” and causal claims require scoped evidence and an explicit comparison.
+- Do not hide uncertainty behind polished prose. Distinguish results from interpretation and proposals from completed work.
+- Do not include chain-of-thought, raw agent chatter, repeated conclusions, filler, or promotional language.
+
+Use the Feynman technique for every technical explanation: state the problem and result in plain language, define specialized terms, give one concrete example or counterexample, explain the mechanism before the abstraction, then add exact technical detail and limitations. Plain language must not erase precision or uncertainty.
+
+### Academic workflow and independent review
+
+For research questions, papers, benchmarks, evaluations, and result-bearing reports, use the smallest applicable Academic Research Suite workflow when it is installed. Use Socratic scoping when the research question is vague, the experiment workflow for design or reproducibility validation, and the integrity/reviewer workflow for claim-source alignment and adversarial review. Do not claim ARS coverage unless that workflow was actually loaded and run.
+
+After an authoring pass, run a fresh read-only empirical review. The reviewer must inspect raw artifacts instead of trusting the PR narrative, preregister its acceptance criteria before judging results, and test the strongest plausible alternative explanation. This is procedural independence, not statistical or institutional independence.
+
+For empirical work, reviewers must check leakage/contamination, sample construction and exclusions, baseline parity, effect sizes and uncertainty, multiple comparisons, stopping rules, selection/survivorship bias, confounds, failed or negative runs, and whether the conclusion exceeds the evaluated setting.
+
+### Review guidelines
+
+- Correct false or stale claims conspicuously. Name what is retracted, provide the replacement, and update every headline or summary that depended on it.
+- Reviewers must request changes when a substantive claim lacks traceable evidence, a result cannot be reproduced from the recorded information, validation is overstated, or the description is dominated by unedited agent output.
+- Do not approve or merge result-bearing work while required evidence or reproduction artifacts are missing. `UNKNOWN` is acceptable for work in progress, not for a claimed conclusion.
+- Report a finding only when you can name the affected file/line or artifact, the evidence, the consequence, a reproduction or verification path, and your confidence. Do not manufacture issues to fill a quota; formatting preferences are not bugs.
+- Do not put secrets, credentials, private keys, tokens, raw participant data, customer data, or unpublished private corpora in prompts, PR bodies, logs, fixtures, artifacts, or commits. Use secret names and unmistakably redacted placeholders.
+<!-- efficient-systems:research-standard:end -->

CLAUDE.md

@@ -65,3 +65,11 @@ store/db.go + store/schemas.go                ├─→ search/graph.go(search)
 - `prototype/` is the retired Python v0 — reference only, don't extend it.
 - `docs/facts.md` documents the fact model; `docs/architecture.tex` the system.
 - `install-daemon` branches on OS: launchd plist on macOS, systemd user unit on Linux (needs `loginctl enable-linger` to survive logout). README's install path (`/opt/homebrew/bin`) is macOS-specific.
+
+<!-- efficient-systems:research-standard-pointer:start -->
+## Research communication standard
+
+`AGENTS.md` contains the mandatory research communication and reproducibility standard for Claude and every other agent in this repository. Read and apply it before making claims, reporting validation, or publishing experimental results. Repository-specific instructions in this file are additive.
+
+For research, benchmark, experiment, or empirical-result work, load the smallest applicable Academic Research Suite workflow when available. After the authoring pass, invoke the fresh read-only `empirical-reviewer` subagent. Do not claim ARS coverage or independent replication unless it actually occurred.
+<!-- efficient-systems:research-standard-pointer:end -->