# reports/ - Generated Output

Derived output that must stay out of git. Two 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](../EVALS.md) for the event contract and what is redacted.

**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](../EVALS.md) § "Whether it runs at
all" for the full precedence and both quantity caps below.

## 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/`.

**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.