Installation

TRACE requires Node.js 18 or newer.

npm install -g trace-coherence

Verify:

$ trace --version
trace v1.0.1

One dependency (yaml). 53 KB total. Zero network calls. Runs entirely offline.

Quick Start (5 Minutes)

New Project

$ trace init

Enter project name: MyProject

  ✓ Created trace.yaml
  ✓ Created .trace/ directory
  ✓ Created .trace/TRACE_STATE.yaml
  ✓ Created .trace/PROJECT_LOG.md
  ✓ Created .trace/HANDOFF.md
  ✓ Created .trace/AI_INSTRUCTIONS.md

Existing Project

$ trace scan

Phase 1: Scanning files...
  Found 47 source files

Phase 2: Detecting anchors...
  ✓ src/models/user.ts (8 consumers)
  ✓ src/config/database.ts (6 consumers)
  ✓ src/middleware/auth.ts (5 consumers)

Phase 3: Detecting test infrastructure...
  ✓ Jest detected

Phase 4: Detecting quality tools...
  ✓ ESLint detected
  ✓ TypeScript compiler detected

Generated trace.yaml with:
  5 anchors, 26 consumer mappings
  Gates: warn mode (gradual adoption)

Open Your First Gate

$ trace gate start

━━━ Start Gate — MyProject ━━━

  ✓ TRACE state exists
  ✓ Baseline tests passing (23/23)
  ✓ No unresolved debt (0/5)
  ✓ Integrity checksums verified
  ✓ Config validation passed
  ✓ AI context generated

  GATE PASSED — Session open.

Tell your AI tool: "Read .trace/AI_CONTEXT.md at the start of each session."

Install the Safety Net

$ trace hook install

  ✓ Pre-commit hook installed.
  Every git commit now runs trace check.
  If coherence fails, the commit is blocked.

Core Concepts

Anchors and Consumers

An anchor is a source of truth. A file that other files depend on. When it changes, its consumers (dependent files) must update too.

anchors:
  - id: user_model
    file: src/models/user.ts
    consumers:
      - src/services/auth.service.ts
      - src/controllers/user.controller.ts
      - docs/api/users.md

If user.ts changes but auth.service.ts doesn't, that's drift. TRACE catches it at gate end.

The Five Pillars

T - Truth Anchoring. One authoritative source per concept. Change the anchor, all consumers must update.

R - Registry Enforcement. Documentation is a verified artifact, not an afterthought.

A - Automated Verification. Tiered testing that grows. Tests never shrink.

C - Controlled Evolution. Complexity thresholds, auto-calibrated to your project.

E - Execution Contracts. Every change type has preconditions and postconditions.

Gate Modes

Block mode: Gate failures stop the session. Use for new projects.

Warn mode: Gate failures print warnings but don't block. Use for gradual adoption on existing projects.

gates:
  start:
    mode: warn
  end:
    mode: block

Starting a Session

$ trace gate start

This validates TRACE state, runs baseline tests, checks for unresolved debt, verifies integrity checksums, validates config, and generates the AI context file.

If anything fails, the gate tells you exactly what and how to fix it.

Check Blast Radius First

Before modifying a core file, see what depends on it:

$ trace impact user_model

Anchor: user_model (src/models/user.ts)
Direct consumers (4):
  - src/services/auth.service.ts
  - src/controllers/user.controller.ts
  - src/middleware/validation.ts
  - docs/api/users.md

If you modify user.ts, update these 4 files before closing your gate.

During Your Session

Code normally. If you're working on something long or risky, drop a checkpoint:

$ trace checkpoint

This captures a git diff snapshot and classifies changes. If your session crashes, the next trace gate start picks up where you left off.

To check health without closing the gate:

$ trace check

Ending a Session

$ trace gate end

━━━ End Gate — MyProject ━━━

Coherence check:
  ✓ All anchors verified (5/5)
  ✓ All consumers synced

Quality checks:
  ✓ Lint passed
  ✓ Typecheck passed

Dependency audit:
  ✓ All 14 dependencies pass moderate policy

  GATE PASSED — Session closed.

If you modified an anchor but forgot a consumer:

  ✗ Consumer sync: user_model changed but
    auth.service.ts not updated

  GATE BLOCKED — Fix consumer drift before closing.

Work Planning

$ trace plan                                      # Show the board
$ trace plan add "Refactor auth" --priority high   # Add item
$ trace plan move ITEM-001 in-progress             # Update status
$ trace plan move ITEM-001 done                    # Complete
$ trace plan release v1.2.0                        # Release notes

Commands: Onboarding

Commands: Coherence

Commands: Session

Commands: Planning

Commands: CI/CD & Maintenance

Commands: AI Process Enforcement

Commands: MCP Server

MCP Server (Autonomous Mode)

The MCP server is what makes TRACE autonomous. Instead of running commands manually, your AI tool calls TRACE functions automatically during conversations.

What it does

When connected, the AI tool gains access to 6 TRACE tools:

Setup

Claude Code

Add to ~/.claude.json or project .claude.json:

{
  "mcpServers": {
    "trace": {
      "command": "trace-mcp"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "trace": {
      "command": "trace-mcp"
    }
  }
}

Kiro

Add trace-mcp as an MCP server in Kiro's MCP settings.

Dependency Governance

AI tools add libraries casually. TRACE enforces rules about what can be added.

dependencies:
  policy: moderate        # strict | moderate | permissive
  max_dependencies: 30
  audit: true             # run npm audit at gate end

  blocked:
    - left-pad
    - "*-polyfill"

  rules:
    require_license: true
    max_age_without_update: 365
    warn_prerelease: true
    blocked_licenses:
      - GPL-3.0
      - AGPL-3.0

strict: Only packages on the allowed list are permitted.

moderate: Packages must pass rules. Blocked packages always rejected.

permissive: Issues flagged but never block.

$ trace deps audit

  Policy: moderate
  Dependencies: 14 total

  evil-pkg@1.0.0
    ✗ BLOCKED: Matches blocked pattern

  old-lib@0.3.1
    ⚠ STALE: No update in 420 days (threshold: 365)
    ⚠ PRE-RELEASE: Pre-1.0 version — API may be unstable

AI Process Enforcement

AI assistants systematically skip TRACE gates when changes feel small or requests come fast. This is a structural behavior pattern, not a one-time mistake. TRACE addresses it at four levels:

Level 1: MCP Server (Autonomous)

The most effective approach. The AI tool calls TRACE functions automatically during conversations via the MCP server. The AI checks impact before modifying files, validates coherence after changes, and checks dependency policy before adding packages. No manual commands needed. See MCP Server setup.

Level 2: AI Instructions

.trace/AI_INSTRUCTIONS.md includes mandatory gate statement rules. The AI must output "TRACE GATE: Opening..." before any edit. This makes skipping visible to the human.

Layer 2: Auto-Session Watch

trace watch detects file changes when no gate is open. It auto-opens a session, logs changes, and closes after inactivity. History is never lost.

$ trace watch

  Monitoring 26 files (5 anchors + consumers)
  Auto-session: ON (closes after 5min inactivity)

  [14:32:05] src/models/user.ts (anchor: user_model)
    ⚠  Anchor modified — 4 consumer(s) may need updating

  AUTO-SESSION OPENED 2026-03-15 14:32:05

  [14:37:05] AUTO-SESSION CLOSING
  ✓ Summary written to PROJECT_LOG.md
  ✓ HANDOFF.md updated

Layer 3: Pre-Commit Hook

The hard enforcement. trace hook install blocks incoherent commits regardless of whether the AI followed process.

$ git commit -m "quick fix"

TRACE: Running pre-commit coherence check...
  ✗ Consumer sync: user_model changed but auth.service.ts not updated
TRACE: Coherence check failed. Commit blocked.

CI/CD Integration

GitHub Actions

# .github/workflows/trace.yml
name: TRACE Coherence Check
on: [pull_request]
jobs:
  trace:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 18 }
      - run: npm install -g trace-coherence
      - run: trace ci --json

To add PR comments:

      - run: trace ci --comment-file /tmp/trace.md
      - uses: marocchino/sticky-pull-request-comment@v2
        with: { path: /tmp/trace.md }

Security

TRACE reads file structure, not file content. Zero network calls. Zero telemetry. One dependency. Nothing phones home.

GDPR: Processes zero personal data.

SOC2: All data stays local.

ISO 27001: SHA-256 integrity verification built in.

HIPAA/PCI: Not applicable (no PII/PHI processed).

Full details: SECURITY.md

Token Optimization

TRACE is designed to minimize token overhead. Four built-in optimizations reduce consumption by 55-60% compared to naive implementation.

Scoped Context

On large projects with many anchors, load only the ones relevant to your current work:

$ trace gate start --scope frontend

Or via MCP:

trace_context({ scope: "frontend" })

Define scopes in trace.yaml:

scopes:
  frontend:
    anchors: [ui_components, styles, routes]
  backend:
    anchors: [user_model, auth_service, database_config]

This filters the AI context to only include anchors in that scope. On a project with 15 anchors, a 5-anchor scope saves 60-70% of context tokens.

Smart Context Deduplication

When the AI calls trace_context via MCP, the server checks if .trace/AI_CONTEXT.md was generated within the last 30 minutes. If fresh, it returns a 3-line summary instead of the full state dump. This prevents redundant reads when the AI already has the context file.

Brief Check Mode

trace_check via MCP returns a single line ("COHERENT - N checks passed, 0 issues") when everything passes. Full details are only returned when there are actual failures. This saves 200-400 tokens per check on healthy projects.

Handoff Truncation

The AI context file and MCP responses include only the last 3 handoff entries instead of the full session history. The complete history stays in HANDOFF.md for reference, but the AI only reads what's recent and relevant.

Token Budget

AI_INSTRUCTIONS.md     500-700 tokens  (read once, high ROI)
AI_CONTEXT.md          300-600 tokens  (scoped + truncated)
MCP trace_context       50-100 tokens  (defers to fresh file)
MCP trace_check         50-100 tokens  (brief mode)
MCP trace_impact       200-400 tokens  (essential, no savings)
─────────────────────────────────────
Total per session    1,300-2,100 tokens

trace.yaml Reference

project:
  name: MyProject

anchors:
  - id: user_model
    file: src/models/user.ts
    consumers:
      - src/services/auth.ts
      - docs/api/users.md

gates:
  start:
    mode: block              # block | warn
    checks: [state_exists, tests_passing, no_excessive_debt, integrity_verified]
  end:
    mode: block
    checks: [anchors_coherent, consumers_synced, tests_passing, thresholds_met]

thresholds:
  max_file_lines: 400
  max_function_lines: 50

quality:
  checks:
    - name: Lint
      command: npm run lint
      on_fail: warn
    - name: Typecheck
      command: npx tsc --noEmit
      on_fail: block

dependencies:
  policy: moderate           # strict | moderate | permissive
  audit: true
  blocked: []
  rules:
    require_license: true
    blocked_licenses: [GPL-3.0, AGPL-3.0]

contracts:
  feature:
    preconditions: [Declare scope, Check anchor impact]
    postconditions: [Update consumers, Update docs, Tests passing]
  bugfix:
    preconditions: [Identify root cause anchor]
    postconditions: [Fix at source, Regression test added]

debt:
  max_accumulated: 5

scopes:                       # Token optimization
  frontend:
    anchors: [ui_components, styles, routes]
  backend:
    anchors: [user_model, auth_service, database_config]

Troubleshooting

"No trace.yaml found"

You're not in a TRACE project directory. Navigate to the project root or run trace init / trace scan.

Gate start fails with "tests not passing"

Your test command in trace.yaml is failing. Run the command manually to see the error. Fix the tests, then retry.

Gate end blocks on consumer drift

You modified an anchor but didn't update all consumers. Run trace impact <anchor_id> to see which files need updating.

"Integrity checksums don't match"

A TRACE file was modified outside a gate. Run trace integrity --generate to regenerate after verifying files are correct.

Pre-commit hook blocks my commit

Run trace check to see what's failing. Fix it, or use trace override "reason" to bypass (creates tracked debt).

AI tool ignores TRACE instructions

Expected. Run trace watch in a background terminal to capture changes automatically. Run trace hook install so commits are blocked regardless.

trace scan missed some anchors

Import analysis catches most but not all dependencies. Manually add missing anchors to the anchors: section in trace.yaml.

Dependency audit flags a package I need

Add it to the allowed list (strict mode) or adjust the rules (moderate mode). If the flag is about staleness or license, evaluate whether the risk is acceptable.