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
2.8 KiB
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 bywikitoolitself and by the harness hooks. See ../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, viatools/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.
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.