Local Tool Reference

Runtime and safety model

All bundled CLIs:

require Python 3.11+ standard library only;
read explicit local JSON, CSV, or Markdown paths;
reject URL-like paths, symlinks, wrong suffixes, oversized inputs, invalid UTF-8, and NUL bytes;
cap inputs at 2 MiB, CSV data at 1,000 rows, cells/Markdown lines at 8,000 characters, and JSON collections at bounded sizes;
reject duplicate JSON keys and require exact ordered CSV headers;
make no network, model, image, subprocess, credential, or environment-variable calls;
write only to an explicit existing local directory;
refuse implicit overwrite unless --force is given;
use private mode (0600) and atomic replacement for generated output.

Reports contain identifiers, counts, rule codes, and line numbers rather than copying scientific prose where practical.

Exit codes

0: input was structurally valid; warnings or human-review gaps may remain.
1: input was parsed, but consistency or required-control errors were found.
2: malformed, unsafe, missing, oversized, or wrong-type input.

No exit code means a hypothesis is true, novel, ethical, safe, feasible, supported, or selected.

1. Hypothesis schema validator

Asset: assets/hypothesis_record_template.json

bash

python3 scripts/validate_hypothesis_schema.py local-record.json
python3 scripts/validate_hypothesis_schema.py \
  local-record.json -o local-validation.json

The exact top-level objects are:

observation;
research question;
hypotheses;
causal estimands;
predictions;
alternative explanations;
null hypotheses;
negative controls;
operationalizations;
analysis plan;
evidence/search link;
causal-bias risk register;
ethics/feasibility gates;
AI-use record.

All hypothesis statuses must be candidate. Causal questions require at least one estimand. Cross-links among candidate, prediction, rival, measurement, analysis, control, and source IDs are checked.

The validator does not read the evidence ledger, test measurements, appraise sources, or interpret results.

2. Operationalization and measurement checklist

Asset: assets/operationalization_template.json

bash

python3 scripts/check_operationalization.py local-operationalization.json

Each measurement item records:

construct, operational definition, population/system, unit/categories, timing, and method completion;
variable role;
validity source IDs and applicability review;
reliability/repeatability;
calibration/quality control;
invariance/comparability;
masking;
missingness;
threshold/cut-point status;
limitations and human review.

planned, unresolved, and pending states are reported as gaps, not converted to scores. A checklist cannot establish measurement validity.

3. Prediction/rival matrix validator

Asset: assets/prediction_rival_matrix_template.csv

Exact header:

text

prediction_id,hypothesis_id,rival_hypothesis_ids,conditions,observable,expected_if_focal,expected_if_rivals,falsifier,indeterminate_result,boundary_conditions,measurement_ids,negative_control_ids,analysis_ids,uncertainty

Use semicolons inside ID-list cells:

bash

python3 scripts/validate_prediction_matrix.py local-matrix.csv
python3 scripts/validate_prediction_matrix.py \
  local-matrix.csv --record local-record.json

Checks include:

unique prediction IDs;
focal candidate not listed as its own rival;
declared focal and rival expectations are not lexically identical;
required falsifier, indeterminate result, boundary, measurement, control, analysis, and uncertainty fields;
optional cross-links to the hypothesis record.

The validator cannot determine whether two predictions are scientifically distinguishable.

4. Causal-versus-associational Markdown lint

bash

python3 scripts/lint_causal_claims.py local-draft.md

Use one claim per annotated line:

markdown

[claim:associational] Exposure X was associated with outcome Y in the observed sample.

[claim:causal][estimand:E1][identification:observational_assumption_dependent][confounding:unresolved][selection:assessed][collider:assessed][reverse-causation:assessed] Under the stated assumptions, intervention X would reduce outcome Y.

Claim types:

causal
associational
descriptive
predictive
mechanistic

Identification values:

randomized
quasi_experimental
observational_assumption_dependent
mechanistic_experiment
other_assumption_dependent

Risk values:

assessed
unresolved
not_applicable

The linter flags a bounded causal lexicon and annotation consistency. It is not a semantic classifier and will have false positives and false negatives.

5. Falsification and negative-control checklist

Asset: assets/falsification_controls_template.json

bash

python3 scripts/check_falsification_controls.py local-controls.json
python3 scripts/check_falsification_controls.py \
  local-controls.json --record local-record.json

For each candidate it requires:

assumptions and boundary conditions;
a prediction-linked falsifier and assumption-failure checks;
at least one discriminating test with focal, rival, and indeterminate outcomes;
a linked null and interpretation limit;
controls including at least one negative-control type;
outcome paths for consistency, challenge, and neither/mixed;
human-review status.

The checker does not validate that a negative control is biologically or causally appropriate.

6. Evidence ledger and search-boundary audit

Assets:

assets/evidence_ledger_template.csv
assets/search_boundary_template.json

Exact evidence-ledger header:

text

source_id,claim_ids,title,authors_or_organization,publication_date,source_type,identifier,url,accessed_on,relation,study_design_or_document_type,limitations,notes

bash

python3 scripts/audit_evidence_ledger.py \
  local-evidence.csv local-search-boundary.json

python3 scripts/audit_evidence_ledger.py \
  local-evidence.csv local-search-boundary.json \
  --record local-record.json

The audit checks:

exact schema and date/HTTPS/identifier formats;
unique source IDs;
source-to-claim links;
source-type and relation declarations;
dated search boundary, queries, limits, stop rule, and novelty status;
optional source, claim, and boundary links to a hypothesis record.

It deliberately performs no network access. It cannot verify that a URL exists, a source says what is claimed, evidence is complete, or an idea is novel.

Allowed novelty states:

not_assessed
requires_specialist_review
supported_by_documented_comprehensive_search

The final state still requires a qualified human and supports only a bounded statement.

7. Preregistration scaffold generator

Asset: assets/preregistration_scaffold_template.md

bash

python3 scripts/generate_preregistration_scaffold.py \
  local-record.json -o local-preregistration.md

The generator:

first runs record validation;
refuses unresolved ethics/safety/feasibility gates;
renders all candidates and rivals without ranking;
escapes inserted text for inert Markdown;
marks the output as an unregistered draft;
leaves repository-, design-, oversight-, and sign-off fields for humans.

It never uploads, registers, timestamps externally, or submits the result.

Suggested local sequence

bash

python3 scripts/validate_hypothesis_schema.py local-record.json
python3 scripts/check_operationalization.py local-operationalization.json
python3 scripts/validate_prediction_matrix.py \
  local-predictions.csv --record local-record.json
python3 scripts/check_falsification_controls.py \
  local-controls.json --record local-record.json
python3 scripts/audit_evidence_ledger.py \
  local-evidence.csv local-search-boundary.json --record local-record.json
python3 scripts/lint_causal_claims.py local-draft.md
python3 scripts/generate_preregistration_scaffold.py \
  local-record.json -o local-preregistration.md

Qualified human review remains mandatory after every command.