TraceLayer makes the why of software traversable. One-line trace:v1 markers declare the semantic relationships that cannot be derived — which work item produced a behavior, which requirement it satisfies, which tests intend to verify it. The engine derives everything else: AST symbol attachment, Git provenance, revision fingerprints, staleness, and runtime evidence. The result is a continuously verified trace graph that agents and reviewers can query instead of loading the whole repository.

Quickstart

Install, trace a repository, and get your first answer in under a minute:

uv tool install tracelayer            # pipx install tracelayer also works

cd your-repo
trace init                            # .trace config + AGENTS.md invariant + .mcp.json (MCP on by default)
trace index --all                     # builds the trace graph
trace verify --all                    # policy check (exit 0 = pass)
trace context <trace-id>              # why does this exist, what verifies it

Trace a behavior by adding one line above it:

# trace:v1 id=impl.demo satisfies=REQ-1
def do_the_thing(): ...

then trace index --all again. Staleness, evidence, hooks, and the CI gate all build on this. Running trace outside a configured repository prints the trace init / trace install next steps.

How it works

flowchart LR
    A[trace:v1 markers] --> B[Marker parser]
    B --> C[AST symbol attachment]
    C --> D[SQLite trace graph]
    D --> E[Git provenance]
    E --> F[Fingerprints and staleness]
    F --> G[Policy evaluation]
    D --> H[Query engine]
    H --> I[context / why / impact / search]
    G --> J[Verify gate]
    J --> K[Hook engine]
    K --> L[Agent context and Stop gate]
    L --> M[CI merge gate]

Markers are the authoring notation; the graph is the product. Paths, line numbers, commit SHAs, and test results are derived — never written into markers — so trace identity survives refactors and evidence can never silently go stale.

Capabilities

Usage

Install

uv tool install tracelayer            # PyPI; pipx install tracelayer also works
trace --help

From a local checkout: uv tool install .. From the repository directly: uv tool install git+https://github.com/carterlasalle/tracelayer.git.

Note: macOS ships a built-in trace (/usr/bin/trace, Apple Instruments). This project installs its trace binary to ~/.local/bin — make sure it precedes /usr/bin in your PATH (which trace should not print /usr/bin/trace).

The first time you run trace outside a configured repository it prints next steps: trace init to enable traceability in the current repo, or trace install to install the skill and hooks into your agent harnesses globally. Set TRACE_NO_HINT=1 to silence that message (e.g. in CI).

Publishing

tracelayer is published to PyPI on version tags via trusted publishing (no tokens stored in CI). Publish a release with:

git tag v0.1.0 && git push origin v0.1.0

Manual publish from a checkout: uv build && uv publish. See .github/workflows/release.yml for the one-time PyPI trusted-publisher setup.

Prerequisites

• Python 3.12+
• uv (dependency management is uv-only; no pip)

uv sync
uv run trace --help

Trace an existing repository:

uv run trace init --root <repo>          # writes .trace/trace.toml + policy.toml
uv run trace index --root <repo> --all
uv run trace verify --root <repo> --all
uv run trace context --root <repo> <trace-id>

Run the full development baseline:

uv run pytest
uv run ruff check .
uv run trace docs generate --check

Architecture

TraceLayer is a single Python package with deliberately narrow module boundaries:

src/tracelayer/
  cli.py                   Typer CLI; business logic lives in modules
  engine.py                Indexing pipeline, verify, staleness, TraceRepository API
  config.py                trace.toml / policy.toml models and loading
  diagnostics.py           TL-rule registry; every failure carries remediation
  protocol/                Marker grammar, parser, ID rules, ontology, generated schema
  discovery/               File enumeration, ignore logic, monorepo scopes
  artifacts/               Markdown, YAML, and generic file-level extraction
  symbols/                 Tree-sitter parsers and marker-to-symbol attachment
  graph/                   Node/edge models, SQLite store, migrations, traversal, fingerprints
  git/                     Provenance, history, diff-range mapping (argv-array subprocess only)
  evidence/                JUnit, Cobertura, normalized JSON, freshness, proof levels
  policy/                  Profiles, lifecycle, waivers, deterministic rule functions
  query/                   context, why, impact, search
  hooks/                   Event handlers and file-backed session state
  audit/                   Bounded semantic-audit packages and external auditor adapter
  migration/               CodeOps and Scry importers

Every module is independently testable; the CLI is a thin shell over the engine.

Safety model

TraceLayer sits in the coding-agent control loop, so correctness is fail-closed by construction:

• Declared claims are never displayed as proven: a test -> exercises -> implementation claim stays unproven until observed execution evidence exists (proof levels L0–L3).
• Derived facts cannot be declared: paths, SHAs, test results, and structural/observed edges are rejected in markers.
• Ambiguity is a diagnostic, never a silent guess: detached markers, unresolved targets, and duplicate IDs are deterministic TL failures with remediation.
• Staleness preserves history: changing a requirement marks downstream review-required; it never deletes evidence.
• Repository text is untrusted data: hooks inject bounded, sanitized summaries; subprocess calls use argv arrays; no shell=True.
• Policy can weaken only deliberately: enforcement-file changes surface as TL063 warnings; waivers are scoped, owned, and expiring.
• CI and the Stop gate run the same engine as the CLI — there is no separate enforcement code path.

Documentation

Installing the agent skill

The canonical skill (canonical layout: SKILL.md + README.md + references/) lives in skills/traceability/ and is bundled with the installed package. Install it with trace install:

trace install --list                     # detect agents and install state
trace install --agent claude-code        # project scope (.claude/skills)
trace install --agent claude-code --global --yes   # ~/.claude/skills
trace install --yes                      # all detected agents, non-interactive

Hooks install for every agent: JSON-merged settings for claude-code (.claude/settings.json) and codex (.codex/hooks.json); file-based hook configs for pi (.pi/hooks.json + wrapper), omp (.omp/hook/hooks.yaml + extension gate), and opencode (opencode.json) — each with an activation note (e.g. pi install npm:@hsingjui/pi-hooks, /hooks-trust in omp). After upgrading the tool, refresh installed copies with trace install --update. The same skill is installable through the skills.sh ecosystem:

npx skills add carterlasalle/tracelayer --agent claude-code

For existing repositories, trace init --skill copies the skill into .agents/skills/traceability/ directly. The same folder is ready for skill registries (e.g. skills.sh, anthropics/skills) — it follows the standard layout and links references directly from SKILL.md.

MCP server (optional adapter)

trace mcp exposes the query surface and the verify gate as MCP tools over stdio, so any MCP-capable agent can connect directly. It is deterministic, local, and optional — the skill + CLI + hooks remain the canonical interface (the spec marks MCP as never required). trace init and trace install (project scope) register it automatically in .mcp.json (merged, other servers preserved; trace init --no-mcp opts out).

Connect Claude Code:

claude mcp add tracelayer -- uv run trace mcp

Or add a project-level .mcp.json for any MCP client:

{
  "mcpServers": {
    "tracelayer": { "command": "trace", "args": ["mcp"] }
  }
}

Tools: status, search, context, why, impact, verify, index. index refreshes the graph from the repository (changed scope by default); the rest are read-only. Results are JSON text.

Contributing

TraceLayer uses protected, squash-only pull requests with required checks. Read CONTRIBUTING.md before making changes. Run uv run trace docs generate --check when editing protocol documentation and trace verify --changed before proposing a merge — this repository traces itself.

License

Apache License 2.0 — see LICENSE.