From c5ed951b2a96a9736db52e9f6cb34fcbe1da696c Mon Sep 17 00:00:00 2001 From: Oleg Sheynin Date: Sat, 25 Jul 2026 00:06:18 +0000 Subject: [PATCH] Release 0.0.1 --- AGENTS.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++ CHANGELOG.md | 7 +++ 2 files changed, 156 insertions(+) create mode 100644 AGENTS.md create mode 100644 CHANGELOG.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f6faffb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,149 @@ +# Agent Instructions + +## Repository purpose + +This repository analyzes test results with Jupyter notebooks and Python or +Bash scripts. Inputs are commonly SQLite databases containing time-series data +and JSON columns, but analyses may use other test-result formats. + +Ignore `__SAV__/`. It is unrelated legacy material, is not part of the active +project, and must not be read, edited, moved, or used as a source of conventions +unless the user explicitly requests it. + +## Active layout + +- `notebooks/`: exploratory and report-oriented Jupyter notebooks. +- `scripts/`: reusable Python and Bash analysis utilities. +- `data/`: local input data. Contents are ignored except for `.gitkeep`. +- `results/`: generated tables, figures, exports, and reports. Contents are + ignored except for `.gitkeep`. +- `requirements.txt`: Python dependencies needed to reproduce repository work. + +Keep reusable logic in `scripts/` and use notebooks to orchestrate analysis, +explain decisions, and present results. Do not create a separate `analysis/` +tree. + +## Python environment + +The intended virtual environment is `~/.pyenv/python3.12-venv`. + +```bash +source ~/.pyenv/python3.12-venv/bin/activate +python -m pip install -r requirements.txt +``` + +Agents may install packages in this environment when needed. Whenever a package +is installed for repository work, update `requirements.txt` in the same change +with a suitable direct dependency declaration. Use `python -m pip`, not bare +`pip`, in documented commands. + +Do not create an in-repository virtual environment unless the user asks for +one. + +## Data handling + +- Treat files in `data/` as local, potentially large, and potentially + sensitive. +- Do not commit SQLite databases, raw test results, or generated results. +- Do not modify source data in place. Write transformed data and exports under + `results/`. +- Use parameterized SQL for values. Do not construct SQL by interpolating + untrusted data. +- Parse JSON columns defensively and preserve missing, malformed, and unexpected + values unless the analysis explicitly defines another policy. +- State assumptions about timestamps, time zones, ordering, units, and duplicate + observations in the notebook or script that relies on them. +- Avoid loading entire databases into memory when a filtered query or chunked + read is practical. + +## Notebook conventions + +- A notebook must run from a fresh kernel, top to bottom, without relying on + hidden interactive state. +- Set random seeds where nondeterminism affects results. +- Keep data paths relative to the repository root and avoid machine-specific + absolute paths. +- Move logic that is reused or substantial enough to test into `scripts/`. +- Clear cell outputs before committing notebooks. Never commit embedded source + data, credentials, or bulky generated output. +- Keep concise Markdown context near analyses: purpose, input assumptions, + method, and interpretation. + +## Scripts + +- Python scripts should expose reusable functions and use a guarded CLI entry + point when executable. +- Bash scripts must start with `#!/usr/bin/env bash` and use + `set -euo pipefail`. +- Prefer explicit CLI arguments over hard-coded paths or parameters. +- Fail with actionable error messages when required data, tables, columns, or + configuration are missing. + +## Verification + +Verification should be proportional to the change. At minimum: + +- Run `pytest` for Python script changes. +- Add or update tests for reusable parsing, transformation, query, and + calculation logic. +- Execute changed notebooks from a fresh kernel with `nbmake`. +- Run changed Bash scripts against a safe fixture or exercise their + non-destructive validation/help path. +- Clear notebook outputs after execution and before committing. + +Useful commands: + +```bash +python -m pytest +python -m pytest --nbmake notebooks +jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace path/to/notebook.ipynb +``` + +If verification cannot be run, report exactly what was skipped and why. + +## Release rules + +- Update `CHANGELOG.md` for every release with the release version, release + date, Git tag, and a concise summary of notable changes. +- Use release headers in `YYYY-MM-DD vMAJOR.MINOR.PATCH` form. +- Use version numbers in `MAJOR.MINOR.PATCH` form. Start this repository at + `0.0.1`. +- Use Git tags in `vMAJOR.MINOR.PATCH` form, matching the changelog version + exactly. For example, version `0.0.1` must be tagged as `v0.0.1`. +- Create the Git tag only after the changelog and any release-related version + changes are complete. +- Do not push release commits or tags unless the user explicitly requests it. + +## Mandatory background review + +Changes to Python scripts, Bash scripts, or notebook code cells require approval +from a separate background reviewer agent before the implementing agent may +declare the work complete. + +The implementing agent must: + +1. Finish the implementation and run the relevant verification. +2. Ask a separate background agent to review the diff for correctness, + reproducibility, data safety, and test coverage. +3. Address every material finding, rerun affected checks, and request follow-up + review when the fix materially changes the code. +4. Report the reviewer outcome in the final response. + +The reviewer must inspect the actual diff and relevant surrounding files; a +self-review does not satisfy this requirement. Documentation-only, +configuration-only, dependency-only, and ignore-rule-only changes do not +require background approval unless they also alter Python, Bash, or notebook +code cells. + +If no background reviewer is available, complete all other work but do not +claim reviewer approval. End the handoff with the exact status: + +`review pending` + +## Change discipline + +- Preserve user changes and avoid unrelated cleanup. +- Do not edit or commit generated files from `data/` or `results/`. +- Do not push or commit unless the user explicitly requests it. The `master` + branch being unprotected does not imply permission to push directly. +- Keep changes focused and explain any new assumptions or dependencies. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a0ebce5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +All notable changes to this project are documented in this file. + +## 2026-07-25 v0.0.1 + +- Established the initial repository structure and project guidance.