Evidence packets

Share the review trail without upgrading static evidence into a promise.

A TraceMap packet is a bounded set of generated artifacts that lets people inspect what the repository scan found, which rules supported the findings, where coverage was reduced, and what still needs human review.

Public claim level: demo. This page explains how to read and share demo-safe packet summaries. It does not claim runtime behavior, production traffic, deployment state, endpoint performance, or release safety.

Packet model

The packet is not a prettier claim. It is the evidence made inspectable.

Source identityRepo label, commit SHA, extractor version, command context, and coverage labels say what was scanned and how complete the result was.

Rule-backed factsFindings retain rule IDs, evidence tiers, source spans, supporting IDs, and limitations so readers can audit the basis for each statement.

Queryable artifactsfacts.ndjson and index.sqlite remain the machine-readable source of truth for local inspection.

Human summariesreport.md, demo summaries, and generated review notes help people navigate the evidence without replacing it.

Gaps includedAnalysis gaps, reduced coverage, unknowns, and deferred checks stay visible instead of being edited out of the story.

Reader paths

Different readers ask different questions, but the packet stays the same.

Managers

Start with coverage labels, changed surfaces, limitations, and reviewer handoff notes before asking for a go/no-go conversation.

Reviewers

Follow rule IDs, evidence tiers, source spans, supporting IDs, and paths to decide which findings need human attention.

Architects

Look for repeated routes, package surfaces, config surfaces, SQL surfaces, and cross-repo paths that explain coupling.

Engineers

Use the packet during a review or incident-adjacent investigation to find static dependency trails without claiming runtime cause.

Tool builders

Consume facts, SQLite tables, reports, and summaries through stable artifacts instead of depending on hidden model state.

Future agents

Resume from specs, state notes, rule IDs, validation output, and generated artifacts instead of reconstructing intent from chat history.

How to inspect

Start broad, then drill into the artifact that supports the claim.

For the public demo, generate the packet locally and share only the public-safe summaries. Keep raw private-repo facts, SQLite indexes, logs, source snippets, SQL values, config values, secrets, local absolute paths, and raw remotes out of public copy.

git clone https://github.com/joefeser/tracemap.git
cd tracemap
./scripts/demo-public.sh .tracemap-demo

# Inspect summary first, then drill into local artifacts.
sed -n '1,160p' .tracemap-demo/demo-summary.md

Packet contents

Each artifact answers a different review question.

scan-manifest.jsonWhat repo, commit, scanner, extractor version, command, and coverage context produced the packet?

facts.ndjsonWhich rule-backed facts were emitted, and what evidence tier, source span, and supporting ID backs each fact?

index.sqliteWhich symbols, endpoints, relationships, packages, SQL surfaces, config surfaces, paths, and gaps are queryable locally?

report.mdWhat human-readable summary, coverage statement, and limitation list should reviewers read first?

logs/analyzer.logWhich analyzer diagnostics explain partial loading, fallback behavior, or reduced coverage?

demo-summary.mdWhich public-safe result can be shared from checked-in sample repositories?

Safe wording

Use language that keeps the claim attached to evidence.

Safe"This endpoint has a static evidence trail through these code and data surfaces."

Safe"This packet shows rule-backed findings and reduced-coverage labels from the scanned commit."

Safe"This change needs review because the packet found a static dependency path with Tier2Structural evidence."

Not safe"TraceMap proves why production is down."

Not safe"TraceMap proves this endpoint is slow, unused, deployed, or safe to release."

Not safe"TraceMap used AI to decide what is impacted."

Boundaries

What the packet deliberately does not prove.

It does not prove runtime reachability, production traffic, performance, deployment state, or incident cause.
It does not replace test results, telemetry, logs, traces, human review, or release approval.
It does not make private raw artifacts public-safe by default.
It does not remove analysis gaps; it labels them so the next reader sees where proof stops.

Next step

Use the packet with the rest of the public site.

Demo walkthrough Current demo result Output artifacts Capability matrix Scan packet example Evidence model Limitations