Root Schema
YAML.trace/config.yml
Defines schema version, model provider endpoints, and team governance policies.
Upstream sourceRepository root & team rules
Downstream consumerCLI parser & worker runtime
RFC-001 Standard
`.trace` keeps understanding close to the code.
The proposed artifact layer connects Git history to human-readable project memory without making a hosted dashboard the durable owner.
Artifact Lifecycle Flow
Schema v0.1 Invariant01AST & Git Extraction
Local Analysis
Deterministic parser inspects commits, diffs, symbol dependencies, and active branch state locally.
Raw source stays on local disk02Durable Repository Record
Approved .trace Artifact
Human-readable Markdown with structured YAML frontmatter is committed or staged directly into .trace/.
Versioned with Git commit tree03Cryptographic Transport Gate
Optional Sync
If hybrid mode is configured, signed metadata & summaries are synchronized over HTTPS.
sourceCodeIncluded: false04Presentation Lens
Dashboard Projection
TRACE web UI indexes and projects artifacts for team navigation without acting as primary source of truth.
Ephemeral presentation layerCore Invariant: The dashboard is a projection layer, never the sole durable owner. Source code is never transmitted.
Directory contract
The versioned record layer.
Every durable output is representable inside .trace/ using human-readable Markdown with machine-readable YAML frontmatter.
Durable Memory
Markdown + Frontmatter.trace/pull-requests/142.md
Dense, evidence-backed change summaries, risk assessments, and migration warnings.
Upstream sourceGit diff + PR metadata
Downstream consumerReviewer briefs & daily digest
Temporal Synthesis
Markdown + Frontmatter.trace/reports/daily/2026-08-20.md
Rollup of repository changes, architectural drift, resolved discussions, and active risks.
Upstream sourceCommitted PRs & decisions
Downstream consumerTeam timeline & dashboard projection
Governance Record
Markdown + Frontmatter.trace/decisions/DEC-2026-0042.md
Lightweight decision records linking PR evidence directly to architectural rules.
Upstream sourceEngineer intent & discussions
Downstream consumerAST rule checks in future PRs
Risk Artifact
Markdown + Frontmatter.trace/risks/RISK-2026-0017.md
Concurrent branch collision warnings and breaking schema divergence notices.
Upstream sourceMulti-branch AST collision engine
Downstream consumerMerge blocker & remediation steps
Operational State
JSON Index.trace/state/sync.json
Local sync sequence tracking, hash trees, and schema validation timestamps.
Upstream sourceCLI execution events
Downstream consumerControl plane reconciler
Specification depth
Four architectural questions.
Formal definitions of storage, relationships, transport, and implementation readiness.
01
What it holds
Human-readable Markdown files accompanied by structured, machine-parsable YAML frontmatter and JSON operational indexes.
- Reports: Daily digests and weekly engineering rollups.
- Pull-request briefs: Dense risk analyses, invariant verifications, and test impact summaries.
- Decisions & risks: Architectural decision records (ADRs) with explicit provenance and links.
- Rules & state: Team invariants, AST memory limits, and branch sync indexes.
.trace/pull-requests/142.md (Schema v0.1)MARKDOWN---
schema_version: "0.1.0"
id: "PR-2026-0142"
artifact_type: "pr_brief"
target_repository: "mathofdynamic/TRACE"
source_branch: "feature/schema-hardening"
base_branch: "main"
evidence_references:
- "commit:9f2c81a"
- "ast_rule:db-memory-bounds"
confidence: "high"
review_status: "verified"
source_code_included: false
created_at: "2026-08-20T07:15:00Z"
---
# PR #142: Schema Hardening & Bounded Invariants
## Findings
- Added bounded JSON parser verification ensuring <1MB memory usage during symbol extraction.
- Zero source code transmitted across network boundary.02
How it relates
Git records code history; AGENTS.md establishes model rules; .trace binds understanding, provenance, and governance into the repository tree.
- Git is the sole authority: Artifacts live in the repo tree, committed or ignored based on team preference.
- Provenance graphs: Every claim links directly to Git SHAs, file path AST nodes, or explicit rule IDs.
- No proprietary database lock-in: Exporting or cloning the repository preserves the entire history of understanding.
.trace/config.yml (Governance & Provenance)YAMLversion: "0.1"
repository: "mathofdynamic/TRACE"
governance:
allow_local_inference: true
source_code_included: false
rules:
- path: ".trace/rules/architecture.md"
enforce_on: ["pull_request", "commit"]
provenance:
require_git_sha_links: true
min_confidence: "medium"03
How it travels
Identical schema across Local CLI, CI pipelines, and Cloud control planes. Sensitive credentials and raw code are excluded by design.
- Unified schema contract: The exact same artifact format is parsed by local CLI, GitHub Actions, and TRACE Cloud.
- Strict redaction gate: Credentials, tokens, raw source files, and private prompt contexts are rejected by schema validators.
- Selective synchronization: In hybrid mode, teams approve exactly which artifact types leave the boundary.
Artifact Transport Validator InvariantJSON{
"$schema": "https://trace.dev/schemas/v0.1/artifact-transport.json",
"invariants": {
"sourceCodeIncluded": false,
"secretsIncluded": false,
"rawPromptsIncluded": false
},
"supportedRuntimes": ["cli", "github-actions", "cloud-worker"]
}04
Current state
Experimental RFC-001 standard. Version 0.1 schema implementation in progress with strict validation test suites.
- Active reference implementation: In-tree Markdown serializers, Zod validators, and CLI readers.
- Backward compatibility guarantee: Versioned frontmatter enables progressive schema migrations.
- Open specification: Independent of any proprietary cloud hosting or specific LLM vendor.
Specification Stability & Version MatrixJSON{
"specification": "RFC-001",
"status": "Experimental / RFC",
"currentSchemaVersion": "0.1.0",
"validatorSuite": "packages/trace-rules",
"conformance": "100% in-tree coverage"
}