trace

/trace: expose the query logic behind every number

Renders and shares one self-contained HTML that ties each reported number (a finding) back to the query that produced it, labeled by confidence: cited (the agent named the query), value-match (a query's captured result_value equals the number), or inferred (nearest query in time). Unmatched findings and orphan queries are shown, not hidden. An unverified number is the most important thing to surface. This is the on-demand artifact for any "prove it" moment.

It reads the analysis record, query log, bounded result previews, findings manifest, action log, and reconciler.

Steps

1. Resolve the analysis. Read the current analysis record:

   python3 -c "
   import sys; sys.path.insert(0, '.')
   from helpers.knowledge.analysis_context import current_analysis
   print(current_analysis() or '')
   "
   

   If there is no current analysis, there is nothing to trace yet. Say so and stop (or, for a past run, point build_trace at that analysis_id explicitly).

   Interactive analysis provenance always remains under the repository's top-level working/ directory. The analysis output directory is only where the shareable HTML and written review go. Do not create or copy another current-analysis.json, and do not relocate the query log.

2. Verify the findings manifest. If reported numbers were not registered, do not pretend a trace exists. Read the saved analysis and query log, then register each reported number with the exact supporting query IDs. Record derived values with their formula and source finding IDs. Never label a timestamp-only guess as a verified link.

3. Build + render the trace. Use the lifecycle command so all inputs come from the canonical provenance store and the HTML goes to the recorded output directory:

   python3 scripts/analysis_trace.py build
   

   This also writes working/provenance_<analysis_id>.json and working/trace_receipt_<analysis_id>.json.