Skip to content

Latest commit

 

History

History
42 lines (31 loc) · 3.35 KB

CONTRIBUTING.md

File metadata and controls

42 lines (31 loc) · 3.35 KB

Contributing to FunnelScript Research

This repository holds FunnelScript's research contracts, falsifiable hypotheses, architecture decisions, evaluations, and manuscripts. The application repository owns the compiler, interpreter, CLI, tests, packaged Standard Library, and Web Studio.

Repository map

Path Purpose
spec/ Language and execution contracts, hypotheses, grammar, JSON Schema
evals/ Observations and falsification evidence against the specifications
paper/ Academic manuscript and references; claims need independent evidence
notebooks/ Research notebooks and exploratory calculations
docs/ Strategy and ecosystem proposals, not necessarily shipped features
DECISIONS.md Accepted architecture decisions
DEBATES.md Open trade-offs and counterarguments
OUT_OF_THE_BOX.md Speculative ideas requiring evaluation

Research-first contribution workflow

  1. Cite a theoretical or observed anchor. Distinguish proposed mechanisms from implemented capabilities and experimentally validated results.
  2. State a falsifiable hypothesis, a counterexample, and the invariant or acceptance criterion in the relevant file under spec/.
  3. Record the test procedure and actual outcomes under evals/. Link a concrete application test or GitHub Actions run when the claim depends on implementation.
  4. Update the accepted decision, debate, and hypothesis records if the design boundary changes. Keep the research and application documentation aligned.
  5. Run the same full research test suite as CI and verify the diff before submitting:
python3 -m pytest -q
git diff --check

pytest is required for the full research regression suite, including the documentation-link contracts and other research oracles. python3 -m unittest discover -s tests -v is an optional narrower smoke check only. These tests do not verify external URLs, scientific claims, or the behavior of the application. Research tests require pytest; application dependencies are not installed in this repository.

Compiler and runtime changes

Work on parsers, World rules, CLI, Python regressions, or Bun belongs in funnelscript/funnelscript. Follow its contributor guide and local AGENTS.md. Reference the relevant research hypothesis and then run the application's own verification suite there. Do not run uv run pytest or bun test as if the research checkout contained the implementation.

Evidence and language standards

  • Use English for tracked research and implementation files.
  • Do not label a simulation reproducible merely because it produces a fixed seed. Separate model assumptions, fitted data, uncertainty, and out-of-sample validation.
  • Report failed hypotheses and reproducible failure lessons; do not alter tests or benchmarks just to obtain a passing result.
  • Do not publish credentials, confidential market data, unverifiable financial returns, or predictions disguised as measurements.