Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (trace-coherence) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

TRACE — Structural Coherence Engineering

Your AI writes great code. TRACE keeps it coherent.

When AI tools help you build software, files drift out of sync across sessions. An anchor changes but its consumers don't. Docs fall behind. Complexity creeps in. Nobody notices until production breaks.

TRACE enforces structural integrity automatically — so you ship with confidence, not crossed fingers.

Install

npm install -g trace-coherence

Quick Start

New project:

trace init           # Scaffolds trace.yaml + .trace/ directory
trace gate start     # Begin session
# ... code ...
trace gate end       # Validates everything before you close

Existing project:

trace scan           # Auto-detects anchors, consumers, tests, quality tools
# Review trace.yaml, adjust if needed
trace gate start     # Begin session (warn mode — gradual adoption)

Five Pillars

Pillar	What it checks
Truth Anchoring	Every concept has one authoritative source. Change the anchor, all consumers must update.
Registry Enforcement	Documentation is a verified artifact, not an afterthought.
Automated Verification	Tiered testing that grows. Tests never shrink.
Controlled Evolution	Complexity thresholds, auto-calibrated to your project.
Execution Contracts	Every change type has preconditions and postconditions.

All Commands (22)

Onboarding

Command	What it does
`trace init`	New project — full enforcement from day one
`trace scan`	Existing project — auto-detection + baseline + quality tool detection

Daily Workflow

Command	What it does
`trace gate start`	Session start + integrity check + config validation + AI context
`trace gate end`	Session end + quality tools + consumer sync + planning + metrics
`trace checkpoint`	Crash recovery + auto-observation (git diff) + context refresh
`trace override "reason"`	Emergency bypass with tracked debt

Coherence

Command	What it does
`trace check`	Full 5-pillar coherence validation
`trace status`	Quick health overview
`trace deps <id>`	Dependency graph + transitive impact analysis
`trace impact <id>`	Pre-work blast radius + consumer sync snapshot
`trace search "query"`	Full-text search across all TRACE artifacts

Security

Command	What it does
`trace integrity`	SHA-256 tamper detection for TRACE files

Planning

Command	What it does
`trace plan`	Kanban-style backlog board (YAML)
`trace plan add "title"`	Add item with `--priority` and `--sprint`
`trace plan move ID status`	Move item between columns
`trace plan release v1.0.0`	Auto-generate release notes from completed items

CI/CD

Command	What it does
`trace ci`	PR-scoped analysis with `--json` and `--comment-file`
`trace metrics`	Outcome analysis + threshold calibration (one-way ratchet)

Maintenance

Command	What it does
`trace validate`	Check trace.yaml for errors, typos, and "did you mean?" suggestions
`trace upgrade`	Add missing config sections — schema migration without data loss
`trace watch`	Monitor files + auto-session when AI skips gates
`trace hook install`	Install pre-commit hook (blocks incoherent commits)
`trace hook uninstall`	Remove pre-commit hook
`trace hook status`	Check if hook is installed

MCP Server (AI Integration)

Command	Description
`trace mcp`	Start MCP server (AI tools call TRACE automatically)
`trace mcp setup`	Show configuration for Claude Code, Cursor, Kiro
`trace-mcp`	Binary entry point for MCP server (used in config)

The MCP server makes TRACE autonomous. Instead of running commands manually, your AI tool calls TRACE functions automatically:

trace_context — reads project state before coding
trace_impact — checks blast radius before modifying files
trace_check — validates coherence after changes
trace_deps_check — checks dependency policy before adding packages
trace_log — records session activity to PROJECT_LOG

Setup (Claude Code):

// Add to ~/.claude.json or .claude.json
{
  "mcpServers": {
    "trace": {
      "command": "trace-mcp"
    }
  }
}

| trace license | Scan dependencies for license compliance |

Key Features

Anchor Impact Protocol

trace impact user_model    # See blast radius before coding
# ... make changes ...
trace gate end             # Blocks if any consumer is stale

Quality Integration

# trace.yaml — auto-detected by trace scan
quality:
  checks:
    - name: "Lint"
      command: "npm run lint"
      on_fail: "warn"
    - name: "Type check"
      command: "npx tsc --noEmit"
      on_fail: "block"

Config Validation

trace validate    # Catches typos, missing fields, invalid values
# Unknown field "anchrs" — did you mean "anchors"?
# gates.start.on_fail must be "block" or "warn", got "crash"

Schema Migration

trace upgrade     # Adds quality, code_review, contracts... whatever is missing
# + quality — Quality checks section
# + code_review — Code review checklist
# Original config preserved, new sections appended

File Watcher

trace watch       # Monitors anchors + consumers
# [14:23:05] ✓ src/models/user.ts (anchor: user_model) — 142 lines OK
# [14:23:05]   ⚠ Anchor modified — 6 consumer(s) may need updating

CI/CD with PR Comments

# .github/workflows/trace.yml
- run: trace ci --json --comment-file /tmp/trace-comment.md

Outcome-Based Calibration

trace metrics     # After 5+ sessions
# ▸ thresholds.max_file_lines
#   Current: 400 → Suggested: 340
#   93% pass rate over 12 sessions — threshold can be tightened

Two Tracks

Track 1: New projects (trace init) — Full enforcement. Gates default to "block."

Track 2: Existing projects (trace scan) — Auto-detects everything. Creates a baseline. Gates default to "warn." New code is enforced; old files come into compliance gradually. No retrofit moment.

Stats

5842 lines across 21 source files
28 commands covering the full development lifecycle
52 tests with zero-dependency test runner
1 dependency (yaml)
Language-agnostic — TypeScript, JavaScript, Python, Go, Java, and more
Tool-agnostic — Claude, Copilot, Cursor, ChatGPT, or any AI tool
CI-agnostic — GitHub Actions, GitLab CI, or any CI system

License

MIT — Created by Anuraj