chemenu/reports/CONTRACT.md

reports/ - Generated Output

Derived output that must stay out of git. Three kinds live here:

• Lint reports, written by tools/wikitool lint --markdown "reports/Lint Report <YYYY-MM-DD>.md".
• Traces, under reports/telemetry/<session>/trace.jsonl - the append-only record of what a session did, written by wikitool itself and by the harness hooks. See ../EVALS.md for the event contract and what is redacted.
• Bug-report bundles, under reports/bugreport-<UTC stamp>/ and a zip beside each, written by tools/bugreport.py on request - see ../instructions/bug-report.md.

Everything in this directory except this file is gitignored. A lint report is a derived copy of recomputable truth: its structural sections can be regenerated from the tree at any commit, so committing them would create a second, drifting copy of something the tool already answers on demand.

The durable half

A report also carries a ## Semantic Review section, which is the LLM's judgment and cannot be regenerated. Because the file itself is never committed, that judgment must be carried out of here before the pass ends:

• Findings that change a page belong in the page, via wikitool touch / xref / new.
• The summary of the pass belongs in kb/log.md, via tools/wikitool log append --op lint.

A lint pass that leaves its conclusions only in reports/ has lost them.

Traces

A trace is neither recomputable nor durable: rerunning a session produces a different one, and nothing else in the repo can reconstruct it. It is still gitignored, because it records prompts and assistant replies in cleartext and belongs to the machine it ran on, not to the repository. What a trace concludes - a scored eval, a failure taxonomy - is carried out the same way a lint report's judgment is: into kb/, work/, or kb/log.md.

WIKI_TRACE_DIR redirects the tree; WIKI_TRACE turns recording on or off, overriding both the installation-form default (on for a dev checkout, off for a distributed instance - chemenu.telemetry.policy) and a per-checkout .wikitool-telemetry.json; WIKI_TRACE_CONTENT=0 keeps lengths and digests instead of text. See ../EVALS.md § "Whether it runs at all" for the full precedence and both quantity caps below.

Bug-report bundles

A bundle is a snapshot of one machine at one moment, made so that someone else can read what happened here. It is not recomputable and not durable, and it contains private data: machine, user and path names, PATH entries, git remotes and commit subjects, and - when included - the session trace, the chronology and transcripts, which may hold page content and titles. Secrets are removed by the collector; the rest is the reader's to check before a bundle leaves the machine. Nothing uploads it: the channel is the user's choice.

The collector's own wikitool calls run under the session id bugreport-<stamp>, so a reports/telemetry/bugreport-* directory is that run's trace and belongs to no session of yours.

Retention

Lint reports: none. Old ones are local scratch; delete them freely. There is nothing to retire with wikitool rm, because no report is ever a wiki page - lint-report is a contract-only type-spec with no base_dir: and cannot be instantiated under kb/.

Bug-report bundles: none. Delete them freely once they have been read or sent; nothing refers to one afterwards.

Traces: two enforced caps, applied by the writer itself, never by a separate cleanup pass. A byte cap per session trace (default 5 MiB, WIKI_TRACE_MAX_SESSION_BYTES) and a retention limit on the number of session directories under reports/telemetry/ (default 250, WIKI_TRACE_KEEP_SESSIONS), both fail-silent like the writer itself. Neither ever removes a session directory in bulk - only the trace.jsonl/.limit files a cap's own rule names, and only once the directory is otherwise empty.