TRACE
Start with TRACE

Product Architecture

A calm system for understanding software change.

TRACE connects change intent to implementation, evidence, impact, decisions, risks, conflicts, and remaining work — keeping intelligence portable across teams and AI agents.

System Architecture Flow
Reasoning Pipeline
01Intent
Goal / RFCWhy this change exists
02Change
GitHub PRWhat files and symbols changed
03Evidence
Local AST ChecksDeterministic rule evaluation
04Intelligence
TRACE ReasoningChange briefs & multi-PR collisions
05Record
.trace ArtifactDurable repository memory in Git

Core Capabilities

Layered intelligence across the change lifecycle.

Each capability maps directly to a verified stage of the reasoning pipeline.

01Pipeline Stage 02 → 03 · Change & Evidence

PR intelligence

A concise brief for intent, affected surfaces, evidence, findings, incomplete work, and recommended review.

Deterministic engine active · Local CLI validated
PR #41 Intelligence Brief · example-repositoryIllustrative example · Deterministic
Verified rule: Deterministic Memory Bounds Policy on ring-buffer stream.
stream.rs:48 · AST bounded allocation verified · 0 secret leaks
Verification: Deterministic AST · Status: Ready for review
02Pipeline Stage 03 → 04 · Multi-Branch Intelligence

Concurrent-change conflicts

Reason across active work simultaneously, not only one pull request at a time. Deterministic overlap and semantic conflict signals remain strictly separate.

Multi-PR overlap analysis · Separate deterministic & semantic signals
Shared workspace · Collision DetectedIllustrative example · Attention Required
Concurrent schema mutation collision between PR #88 and PR #89 on user_workspaces table.
Finding: schema-collision-001 · Classification: Deterministic schema collision
Resolution: Staged migration ordering required before merge
03Pipeline Stage 04 · Synthesis & Temporal Memory

Daily and weekly reports

Summarize meaningful change, decisions, risks, and unresolved coordination questions without turning engineering into individual productivity scores.

Markdown & YAML frontmatter · Portable artifact
Daily Project Report · 2026-08-19Illustrative example · Current HEAD
3 changes reviewed · 1 architectural decision recorded · 0 productivity rankings
Commit: 1e9b8a4746f3 · Provenance: example-repository
Output: .trace/reports/daily/2026-08-19.md
04Pipeline Stage 05 · Durable Storage Authority

A durable project record

Decisions, risks, evidence, and reports live as readable .trace artifacts. The dashboard helps navigate the record, never becomes its only copy.

Open specification · Versioned repository files
.trace/decisions/0001-single-direction-sync.mdIllustrative example · Git-native
Decision: Single-Direction Local-to-Cloud Intelligence Synchronization with constant-time digest verification.
Schema: v0.1 · Invariant: sourceCodeIncluded: false · 100% offline accessible
Repository authority: Git tree is the sole single source of truth

Privacy & architectural boundary

Strict local-first boundaries by design.

Verification occurs where your code lives. Raw source code never leaves your perimeter.

Execution Engine

Analysis stays local

Parsing, AST symbol extraction, and deterministic rule evaluation execute entirely in your local environment.

Privacy Invariant

Source code is never synchronized

The .trace contract strictly enforces sourceCodeIncluded: false and codeSnippetsIncluded: false on all artifact payloads.

Hybrid Policy

Selective metadata synchronization

Only explicitly approved, source-free summaries and decisions are transmitted when hybrid mode is active.

Data Sovereignty

Git as the sole authority

The dashboard is an ephemeral lens. If TRACE servers disappear, your .trace directory remains complete and readable in Git.

Current implementation truth

Phase 05 Verified Universe

What exists and works now

  • Local CLI analysis & deterministic rule evaluation
  • .trace version 0.1 schema specification & validator
  • Concurrent change & schema migration collision detectors
  • Daily & weekly report generation in Markdown with YAML metadata
  • Web preview dashboard, command center & repository switcher
  • Zero source code transmission invariant (sourceCodeIncluded: false)

What is planned for future phases

  • Automated GitHub Checks and check-run annotations
  • Cloud-hosted background job orchestration & webhooks
  • Multi-tenant team administration & organization policies
  • Continuous cross-repository dependency synchronization
Read the .trace artifact specification →·Review security & privacy architecture →