Installation

TRACE requires Node.js 18 or newer.

npm install -g trace-coherence

Verify:

$ trace --version
trace v1.0.2

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.

Zero-Config Activation

After initial setup (trace init or trace scan), a single command makes TRACE fully autonomous:

$ trace activate

━━━ TRACE Activate — Full Automation ━━━

  ✓ pre-commit installed — Blocks incoherent commits
  ✓ post-commit installed — Regenerates AI context after commit
  ✓ post-checkout installed — Regenerates AI context on branch switch
  ✓ post-merge installed — Regenerates AI context after pull/merge

  TRACE is now fully autonomous.

What happens after activation:

Pre-commit: Every git commit runs trace check. If coherence fails, the commit is blocked.

Post-commit: After every successful commit, AI context is regenerated so the next AI session has fresh state.

Post-checkout: When you switch branches, AI context is regenerated for the new branch's structure.

Post-merge: After git pull or merge, AI context is regenerated to reflect incoming changes.

You never need to run trace gate start again. The hooks handle everything.

$ trace activate status    # Check which hooks are active
$ trace deactivate         # Remove all TRACE hooks

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 }

GitHub Action Template

TRACE includes a production-ready GitHub Action template. Copy it from the CLI:

$ cat $(npm root -g)/trace-coherence/templates/github-action.yml

Or copy from GitHub.

The template includes:

Full git history (fetch-depth: 0) for accurate diff analysis.

PR comment updates — finds and updates existing TRACE comments instead of creating duplicates.

Fail on critical — blocks PR merge when coherence check fails.

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

Policies

Define organization and team rules that the AI must follow. Policies are injected into AI_CONTEXT.md and the MCP trace_context response, so the AI reads them before starting work.

policies:
  data:
    - "Never paste client production data into AI tools"
    - "Never paste credentials, secrets, or API keys"
    - "One client per session"
    - "Client business logic is confidential"
  compliance:
    - "All code must pass security scan before merge"
    - "No AI-generated code ships without human review"
    - "Maintain audit trail for all AI-assisted changes"
  workflow:
    - "One ticket per session — scope changes to ticket"
    - "All sessions must have gate start and gate end"
    - "Minimum 80% test coverage for new code"

Categories are flexible. Use whatever grouping makes sense for your team: data, compliance, workflow, security, naming, or any custom category.

Organization Config

For teams with multiple projects, define org-wide defaults in a shared config file. Every project inherits these defaults automatically.

Setup

Place your org config at either location:

# Per-project (committed to repo):
.trace/org-config.yaml

# Per-user (applies to all projects):
~/.trace/org-config.yaml

Example

organization:
  name: "YourCompany"

policies:
  data:
    - "Never paste client production data"
    - "Never paste credentials or secrets"
  compliance:
    - "All code must pass security scan before merge"

dependencies:
  policy: moderate
  blocked: ["*-polyfill"]
  rules:
    blocked_licenses: [GPL-3.0, AGPL-3.0]

quality:
  checks:
    - name: "Secrets scan"
      command: "npx gitleaks detect --no-git"
      on_fail: block

thresholds:
  max_file_lines: 400

How Merging Works

Policies: Org and project policies combine. If both define data rules, you get all rules from both.

Dependencies: Blocked lists merge. Project policy mode overrides org if specified.

Quality checks: Org checks are added to project checks (deduplicated by name).

Thresholds: Project values override org values.

JSON Reporting

For dashboards and org-wide visibility:

$ trace metrics --json

Outputs a JSON report with project name, organization, session pass rate, anchor/consumer counts, debt level, policies, and failure patterns. Pipe this to your observability tools for cross-project aggregation.

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]

Acknowledged Drift

When TRACE reports the same drift warning every session, it becomes noise. If specific drift is intentional (a deprecated doc, a legacy file, an accepted deviation), acknowledge it so it stops appearing in checks:

$ trace acknowledge user_model docs/old-api.md "Deprecated, removing in v2"

  ✓ Acknowledged drift: user_model → docs/old-api.md
  This consumer will be skipped in future drift checks.

Acknowledged drift is stored in .trace/ACKNOWLEDGED_DRIFT.yaml and filtered from both trace check and trace gate end consumer sync checks.

Managing Acknowledged Drift

$ trace acknowledge --list          # Show all acknowledged entries
$ trace acknowledge --remove 2      # Remove entry #2 (re-enables checking)

When acknowledged drift is filtered, the output shows the count:

  ✓ user_model: 5 consumer(s) coherent (1 acknowledged)

Planning Toggle

Teams using Jira, Linear, or GitHub Issues can disable the PLAN.yaml check at gate end:

planning:
  enabled: false  # Skip plan checks at gate end

The built-in Kanban board (trace plan) still works — this just prevents gate end from nagging about plan updates. Default is true (plan checks active). Ideal for vibe coders who don't use external tracking tools.

Smart Insights

TRACE doesn't just block bad commits — it proactively surfaces problems before they become expensive.

Coherence Score (0-100)

A single number for structural health. Shown in trace status, trace check, trace metrics, and the MCP trace_status response.

$ trace status

  Coherence: 87/100 ████████████████░░░░

Scoring: anchors exist on disk (30pts), consumers synced (30pts), debt level (20pts), config completeness (10pts), complexity compliance (10pts). Target 80+ for healthy projects.

Auto-Anchor Discovery

During trace check, TRACE scans import graphs and suggests files with 3+ importers that aren't registered as anchors:

  Suggested anchors (files with 3+ importers not in trace.yaml):
    → src/utils/formatting.ts (6 importers)
    → src/hooks/useAuth.ts (5 importers)

Dead Consumer Detection

Flags consumer relationships where the consumer file no longer references the anchor:

  Stale consumers (no longer reference their anchor):
    ○ user_model → src/old/legacy-auth.ts
    Consider removing from trace.yaml consumers list.

Complexity Trends

In trace metrics, anchor files approaching the complexity threshold are flagged:

  Complexity Watch:
    ▲ auth_service: 380 lines (95% of 400 threshold)
    → user_model: 290 lines (73% of 400 threshold)

Git Co-Change Analysis

During trace scan, if git history exists, TRACE detects files that frequently change together:

  Git co-change patterns:
    ↔ src/models/user.ts ↔ src/services/auth.ts (92% co-change, 12 commits)
    ↔ src/config/db.ts ↔ prisma/schema.prisma (88% co-change, 8 commits)

This catches relationships that imports miss: a model and its documentation, a schema and its migration.

Session Summary

At trace gate end, a summary shows what the session accomplished:

  ━━━ Session Summary ━━━
  Anchors: 8  Consumers: 24  Score: 87/100

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.