torben
82a22eaa93
Files changed: - .gitea/workflows/ci.yml - .gitignore - CHANGES.md - EVALS.md - INSTALL-MCP.md - INSTALL.md - VERSION - instructions/setup-instance.md - reports/CONTRACT.md - tools/CONTRACT.md - tools/chemenu/commands/doctor.py - tools/chemenu/config.py - tools/chemenu/mcp/server.py - tools/chemenu/telemetry/policy.py - tools/chemenu/telemetry/schema.py - tools/chemenu/telemetry/writer.py - tools/chemenu/tests/conftest.py - tools/chemenu/tests/test_doctor.py - tools/chemenu/tests/test_mcp_server.py - tools/chemenu/tests/test_telemetry_emit.py - tools/chemenu/tests/test_telemetry_policy.py - tools/chemenu/version.py
54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
# 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.
|