velocity.report: Instructions file for Codex

Repository instructions

This is the canonical repository-wide guide for coding agents. Tool-specific entry points import or link to this file; update shared agent instructions here rather than copying them into wrappers.

Read the coding standards for repository conventions. Domain-specific knowledge remains in its canonical module under .github/knowledge/; reference that module when adding guidance instead of restating its rules here.

Keep experiment findings in Git and raw outputs local

Commit detailed, human-readable experiment reports in docs/. Preserve the question, methods, arm definitions, numerical findings (including per-case summaries where they affect the decision), interpretation, limitations, frozen provenance, and recommendations. Reports must distinguish observed measurements from physical validation and explain what the evidence does not establish. Link reports from the relevant README, plan, and development-log entry. A report is part of the engineering record, not disposable output; do not remove it when cleaning up raw results.

Never commit raw experiment, replay, analysis, or benchmark outputs on any branch or PR. Recordings, row-level data, generated metric/configuration dumps, runtime logs, coverage output, database snapshots, and campaign state belong outside the checkout or in ignored local output directories. Do not attach raw output to a report or rename it into docs/ to evade this rule. Edited summary tables and numerical findings that explain the experiment belong in the written report.

Directories named results at any depth are local output only. Never stage them, create a raw results branch, or bypass the ignore rule with git add -f. Keep reusable implementation and hand-authored test fixtures in their normal source locations. Reports must be readable without links to untracked repository output; describe archived evidence and retain provenance identifiers without importing raw artefacts.