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.

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

Quick start

Install

From the repository (no publish step needed):

uv tool install git+https://github.com/carterlasalle/tracelayer.git
trace --help

Or install from a local checkout: uv tool install .. The wheel is verified against a clean venv with uv build; a PyPI publish is the planned next step.

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 are merged for claude-code (.claude/settings.json) and codex (.codex/hooks.json) in project scope; other agents get the skill only — see adapters/<harness>/README.md for their hook setup. 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.

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.