feat(docs): enhance README and build pipeline rules for clarity

- update README to clarify the exclusion of bulk artifacts from git
- specify committed curated results subset in README and rules
- improve descriptions of output directories and their contents
- refine details on the pipeline's data generation and reporting processes
This commit is contained in:
administrator
2026-07-12 11:18:16 -04:00
parent 35d2bdadbd
commit b4270b0247
3 changed files with 893 additions and 28 deletions

View File

@@ -31,10 +31,14 @@ out/
- Tasks communicate exclusively through these artifacts - never through
shared in-process state
(see [code-python-style.md](code-python-style.md)).
- **`./out/` is git-ignored** (except nothing - the whole tree). Sources
of truth are the specs, the rules, and the code; artifacts are
reproducible from them ([data-determinism.md](data-determinism.md)).
Never commit generated artifacts "for convenience".
- **The bulk of `./out/` is git-ignored.** Sources of truth are the
specs, the rules, and the code; artifacts are reproducible from them
([data-determinism.md](data-determinism.md)). A curated results subset
IS committed (owner decision, 2026-07-11): `out/report/` (REPORT.md,
charts, tables, diagrams), `out/config/` (lab_config.yaml,
hw_prices.yaml), and the `out/.done/` markers - exactly the exceptions
listed in `.gitignore`. Never commit the bulk artifacts (corpus,
databases, stores, archives, raw benchmark data) "for convenience".
## 2. Completion markers
@@ -92,7 +96,9 @@ out/
- **Writing an artifact outside `./out/`** or a task writing into another
task's output directory.
- **Committing `./out/` content to git.**
- **Committing bulk `./out/` content to git** (corpus, databases, stores,
archives, raw benchmark data) - only the curated subset in `.gitignore`
(`report/`, `config/`, `.done/`) is committed.
- **A marker written on partial success** - see
[code-error-handling.md](code-error-handling.md).
- **Running benchmarks while converters are still running.**