tracefork 0.1.0__tar.gz

tracefork-0.1.0/.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,toml,json,md}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

tracefork-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Report a problem
+labels: bug
+---
+
+## Description
+
+A clear, concise description of the bug.
+
+## Reproduction
+
+- Command(s) run (e.g. `tracefork replay ...`, `tracefork fork ...`, `tracefork blame ...`):
+- Tape involved (attach or describe how it was recorded, if applicable):
+- Minimal steps to reproduce:
+
+## Expected vs actual
+
+**Expected:**
+
+**Actual:**
+
+## Environment
+
+- `tracefork --version`:
+- Python version:
+- OS:
+
+## Determinism-boundary note
+
+Did the agent under trace read all time/id nondeterminism only via `NondetSource`
+(no direct `datetime.now()`, `uuid`, or `random` calls)? If unsure, say so — this
+affects whether replay/fork/blame can be expected to be bit-exact.

tracefork-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/pratik916/tracefork/security/advisories/new
+    about: Please report vulnerabilities privately, not as public issues.

tracefork-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest an idea
+labels: enhancement
+---
+
+## Problem
+
+What problem are you trying to solve? What's missing or painful today?
+
+## Proposed solution
+
+Describe the feature or change you'd like to see.
+
+## Alternatives
+
+What alternatives or workarounds have you considered?
+
+## Scope/invariants impact
+
+Does this affect any of tracefork's core invariants? Please note if it touches:
+
+- Offline / $0 / no-key operation for tests, spike, `validate`, or the demo
+- The determinism boundary (agent reads time/ids only via `NondetSource`)
+- The verifier's hash-check proof (vs. assertion) or the drift negative control
+- Packaging/PyPI metadata or the public CLI surface

tracefork-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

tracefork-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## What & why
+
+<!-- Summarize the change and the motivation behind it. -->
+
+## Checklist
+
+- [ ] `uv run pytest -q` is green (65 offline tests, $0, no key)
+- [ ] `uv run ruff check .` is green
+- [ ] `uv run ruff format --check .` is green
+- [ ] `uv run mypy src/tracefork` is green
+- [ ] `uv run tracefork validate --check` is green (if this PR touches `blame.py`, `fork.py`, or `faults.py`)
+- [ ] Determinism-boundary invariants respected: the agent reads time/ids only via
+      `NondetSource`; no new networked test; the verifier still proves via hash-check
+      (not assert); the drift negative control still fails as expected
+- [ ] Commit messages are conventional-commit style, with no `Co-Authored-By: Claude`
+      or other AI-authorship trailer

tracefork-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Ruff lint
+        run: uv run ruff check .
+      - name: Ruff format check
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run mypy src/tracefork
+      - name: Tests + coverage
+        run: uv run pytest -q --cov --cov-report=term-missing
+      - name: Self-validation regression gate
+        run: uv run tracefork validate --check
+      - name: Build distribution
+        run: uv build
+      - name: Twine check
+        run: uv run --with twine twine check dist/*

tracefork-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+# Publishes tracefork to PyPI via Trusted Publishing (OIDC) — no API token stored.
+# Fires when a GitHub Release is published, or on manual dispatch (e.g. to publish an
+# already-tagged version). Requires a matching trusted publisher configured on PyPI:
+#   PyPI project: tracefork · owner: pratik916 · repo: tracefork
+#   workflow: release.yml · environment: pypi
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tracefork
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tracefork-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+.pytest_cache/
+
+# Spike tape artifacts (regenerated by running the spike)
+*.tape.sqlite
+/tmp_tapes/
+
+# Runtime artifacts (CLI output, regenerated on demand)
+/store.db
+/report.html
+/blame_*.json
+/validation_report.json
+/examples/demo_report.html
+
+# Build, coverage, and tool caches (regenerated on demand)
+/dist/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Local-only planning scaffolding (workspace convention)
+docs/superpowers/
+.beads/
+planning/
+.superpowers/

tracefork-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        files: ^src/tracefork/
+        additional_dependencies: [anthropic, types-requests]

tracefork-0.1.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-02
+
+### Added
+
+- **Record/replay** at the Anthropic SDK's httpx transport boundary
+  (`TraceforkTransport` / `AsyncTraceforkTransport`), streaming-SSE capable, with
+  bit-exact replay proven by sha256-checking every replayed request body against the
+  recorded tape — and drift detection that fails loudly on divergence rather than
+  silently falling back to the network.
+- **Content-addressed tape format** (`Tape`) — sha256 blobs plus an ordered event log,
+  JSON + base64 (never pickle), persistable to SQLite, with a hash-chain `digest()`
+  fingerprint.
+- **Nondeterminism virtualization** (`NondetSource`) — the only path through which an
+  agent reads time and ids, with `RecordingNondet`, `ReplayNondet`, and a `DriftingNondet`
+  negative control that proves the divergence detector actually detects divergence.
+- **Three-phase fork engine** (`ForkEngine`, `ForkTransport`) — prefix-replay ($0),
+  mutation-injection (swap a response), and tail-record (the recorded counterfactual
+  continuation), re-running the same agent that produced the original tape.
+- **Causal blame engine** (`BlameEngine`) — forks each step `k` times, re-runs the agent,
+  grades outcomes via an `Oracle`, and ranks steps by flip-rate with Wilson score
+  confidence intervals; a `BudgetGovernor` estimates dollar cost from the pricing table
+  and refuses to exceed a caller-supplied budget before making any real API calls.
+- **Fault-injection self-validation suite** (`faults.py`, `validate.py`) — five fault
+  classes with markers embedded in valid Anthropic JSON, scored end-to-end offline
+  against a synthetic fault-aware agent: **1.00 top-1 precision** across all five classes,
+  with an enforced negative-control threshold so the proof isn't vacuous.
+- **Single-file web report/UI** (`report.py`, `server.py`, `web/report.html`) — a
+  dependency-free, three-panel HTML report (timeline, exchange detail, blame ranking)
+  either rendered statically or served live via FastAPI (`serve`, 127.0.0.1, no CORS).
+- **CLI** (`cli.py`, Typer) — `replay`, `verify`, `fork`, `blame`, `report`, `serve`,
+  `validate`.
+- `src/tracefork_spike/` — the original Spike 0 that de-risked bit-exact, no-key replay
+  within the declared determinism boundary.
+
+[Unreleased]: https://github.com/pratik916/tracefork/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/pratik916/tracefork/releases/tag/v0.1.0

tracefork-0.1.0/CLAUDE.md

@@ -0,0 +1,112 @@
+# CLAUDE.md
+
+This file guides Claude Code when working in the `tracefork` repository.
+
+## What this is
+
+`tracefork` is a time-travel debugger for AI agents: record an agent run to a
+content-addressed **tape**, replay it **bit-exact for $0** (hash-verified), fork any
+step, and measure causal blame with confidence intervals — the instrument itself
+validated against runs with injected, known root-cause faults.
+
+**Current state: v1 built.** All five product pillars work offline and are tested
+(65 tests, $0): streaming-capable record/replay with drift detection, the three-phase
+fork engine, the causal blame engine with Wilson CIs and a budget governor, the
+single-file web report/UI, and the fault-injection self-validation suite (5 fault
+classes at 1.00 top-1 precision). `src/tracefork_spike/` keeps the original Spike 0 that
+de-risked the load-bearing assumption (bit-exact, no-key replay within a declared
+determinism boundary). Design/feature list: `../ideas/2026-06-11-tracefork-features.md`;
+spike finding: `SPIKE0.md`.
+
+## Commands
+
+Python is **3.12 via uv**. The tests, the spike, `validate`, the demo, and
+record/replay/fork are offline and $0 — **no `ANTHROPIC_API_KEY`, no network**. Only
+`blame` against a *real* run hits the live API (budget-capped). Always prefix `uv run`.
+
+```bash
+uv sync --extra dev                  # install (anthropic, zstandard, typer, fastapi, uvicorn + pytest)
+uv run pytest -q                     # full offline suite (65 tests)
+uv run pytest tests/test_faults.py::test_validation_runner_fingers_fault_step -q   # one test
+uv run tracefork validate            # self-validation: blame vs injected, known faults
+uv run tracefork validate --check    # regression-gate vs experiments/validation_report_committed.json
+uv run python examples/demo_report.py   # write examples/demo_report.html (the README screenshot)
+uv run python -m tracefork_spike     # the original Spike 0 bit-exact replay receipt
+uv run tracefork --help              # replay, verify, fork, report, serve, blame, validate
+```
+
+## Architecture (the parts that span files)
+
+The spine is a **record/replay seam at the Anthropic SDK's httpx boundary**, plus a
+**nondeterminism-virtualization seam** the agent reads time/ids through. Bit-exactness
+is the contract between them.
+
+The product lives in `src/tracefork/`:
+
+- `nondet.py` — `NondetSource` is the *only* way the agent gets time/ids.
+  `RecordingNondet` draws real values and logs them; `ReplayNondet` serves them back in
+  order; `DriftingNondet` is the negative control (fresh values → forced divergence).
+  `find_divergence()` unwraps a `DivergenceError` from the `APIConnectionError` the SDK
+  wraps transport exceptions in — **keep this; without it a real divergence looks like a
+  network blip.**
+- `transport.py` — `TraceforkTransport` (sync) + `AsyncTraceforkTransport` (async) are the
+  capture seam, streaming-SSE capable (buffer via `.read()`/`.aread()`). Record mode tees
+  request+response bytes into the tape; replay mode serves recorded bytes and
+  sha256-asserts each request body matches (the divergence detector). A replay transport
+  has **no inner transport**, so any unrecorded request is a hard error.
+- `tape.py` — `Tape` is content-addressed (sha256 blobs) + an ordered event log,
+  JSON+base64 in memory, persistable to SQLite, with a hash-chain `digest()` fingerprint.
+  (`to_bytes`/`from_bytes` are JSON, **not pickle** — no arbitrary-code-execution risk.)
+- `recorder.py` — `Recorder` context manager wraps a real `anthropic.Anthropic` at its
+  `_client._transport` seam (via `client.copy(http_client=...)`, so base_url / auth_token /
+  default headers are preserved). Patches `uuid.uuid4` globally; **does not** patch
+  `datetime.datetime` (immutable C type in 3.12+, and a subclass breaks the SDK's pydantic
+  schema builder) — agents needing deterministic clocks read `NondetSource` directly.
+- `fork.py` — `ForkTransport` runs three phases: prefix-replay ($0, request asserted to
+  match the parent), mutation-injection (same request, swapped response), tail-record (the
+  counterfactual continuation). `Branch` carries `prefix_replayed`/`tail_recorded` counts.
+  `ForkEngine.fork()` re-runs the **same** agent that produced the tape.
+- `store.py` — `TapeStore`, SQLite persistence for tapes + the branch DAG.
+- `blame.py` — `BlameEngine.rank()` forks each step `k` times, re-runs the agent, grades
+  via an `Oracle`, counts flips vs. the parent outcome; `wilson_ci()` for intervals;
+  `BudgetGovernor` estimates tail-call cost from `constants.PRICING_TABLE` before spend and
+  `rank()` raises `BudgetExceededError` if the estimate exceeds `budget_usd`.
+- `faults.py` / `validate.py` — 5 fault classes (valid JSON, marker **inside** a content
+  field) + the self-validation runner; a synthetic agent echoes each response forward so an
+  injected fault propagates to a fault-aware tail. `run_all_fault_classes()` scores top-1.
+  **Scope (don't overstate):** the fixture is a positive-vs-inert control on a short tape —
+  it proves the engine is genuinely causal (not a fixed-slot artifact), not that it
+  discriminates among competing causes on long tapes. See README → Validation scope.
+- `report.py` / `server.py` / `web/report.html` — the single-file, dependency-free
+  three-panel UI; `report.py` injects tape JSON (HTML-escaped against `</script>`
+  breakout), `server.py` is FastAPI same-origin (no CORS, binds 127.0.0.1).
+- `wire.py` / `synthetic.py` — Anthropic wire-format builders and the offline
+  Scripted/FaultAware fake transports, in the **package** so production never imports from
+  `tests/`; `tests/fakes.py` re-exports them.
+- `cli.py` — Typer entry point for all seven commands.
+
+`src/tracefork_spike/` holds the original Spike 0 (`fake_llm.py`, `agent.py`, `spike.py`):
+record → save → load → replay → verify + negative control, with its own tests.
+
+## Invariants / conventions
+
+- **Offline and $0 is non-negotiable** for the whole test suite, the spike, `validate`,
+  and the demo — no key, no network. The synthetic transports (`synthetic.py`) are the
+  seam; add to them rather than reaching for the real API. (`blame` on a real run is the
+  one budget-capped exception.)
+- **The agent must read time/ids only through `NondetSource`** — any direct
+  `datetime.now()` / `uuid` / `random` breaks the determinism boundary and the
+  bit-exactness claim.
+- **The verifier proves, not asserts** — every request body is hash-checked against the
+  tape; the negative control must keep failing (drift detected) or the proof is vacuous.
+- **Declared determinism boundary (v1):** single-process (sync **or** asyncio), clock +
+  id nondeterminism captured through `NondetSource`. Threads/subprocess are out of scope;
+  fork and blame additionally assume the agent rebuilds its prefix deterministically (the
+  property replay proves) — see `SPIKE0.md`.
+- **No `Co-Authored-By: Claude` trailer** on commits in this repo (public portfolio repo,
+  sole-author attribution).
+- **Model IDs / pricing / SDK usage:** consult the `claude-api` skill before writing or
+  editing any Anthropic integration code rather than relying on memory.
+- `docs/superpowers/`, `.beads/`, `planning/` are gitignored local scaffolding (but
+  `docs/demo.png` is committed). Runtime artifacts (`store.db`, `report.html`,
+  `blame_*.json`, `validation_report.json`, `examples/demo_report.html`) are gitignored.

tracefork-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail
+address, posting via an official social media account, or acting as an
+appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**godofcode.pratik@gmail.com**. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

tracefork-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to tracefork
+
+Thanks for considering a contribution. tracefork is a small, offline-first project —
+please keep changes in that spirit.
+
+## Dev setup
+
+Python **3.12** via [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync --extra dev
+```
+
+This installs the runtime deps (`anthropic`, `zstandard`, `typer`, `fastapi`, `uvicorn`)
+plus the dev toolchain (`pytest`, `pytest-asyncio`, `pytest-cov`, `ruff`, `mypy`).
+
+## Running everything locally
+
+All of the following are offline and **$0** — no `ANTHROPIC_API_KEY`, no network:
+
+```bash
+uv run pytest -q                        # full offline suite (65 tests, $0, no key)
+uv run tracefork validate               # self-validation: blame vs injected, known faults
+uv run tracefork validate --check       # regression-gate vs experiments/validation_report_committed.json
+uv run ruff check .                     # lint
+uv run ruff format --check .            # format check
+uv run mypy src/tracefork               # type check
+uv run python examples/demo_report.py   # generate the demo report (examples/demo_report.html)
+```
+
+Run the full local gate before opening a PR:
+
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run mypy src/tracefork && uv run pytest -q
+```
+
+CI runs this same gate (plus `tracefork validate --check` and a package build) on every
+pull request.
+
+## Invariants a PR must respect
+
+These are load-bearing for the project's claims and are enforced by review, not just CI:
+
+- **Offline and $0 stays non-negotiable** for the whole test suite, the spike, `validate`,
+  and the demo. If your change needs a new kind of model response or behavior, add it to
+  the offline fakes in `src/tracefork/synthetic.py` rather than hitting the real API. The
+  only intentionally networked path is `blame` against a real run, and that is
+  budget-capped by `BudgetGovernor`.
+- **The agent reads time/ids only through `NondetSource`.** Any direct
+  `datetime.now()` / `uuid` / `random` call in agent code breaks the determinism boundary
+  and invalidates the bit-exactness claim that replay, fork, and blame all depend on.
+- **The verifier proves, it does not assert.** Every replayed request body is
+  sha256-checked against the tape (`transport.py`); don't weaken this to a soft
+  comparison. The drift negative control (`DriftingNondet`) must keep failing — if a
+  change makes it pass, that's a regression in the divergence detector, not a fix.
+
+If you're touching `src/tracefork/recorder.py`, `transport.py`, `fork.py`, or `blame.py`,
+re-read the relevant section of `CLAUDE.md` first — it documents the seams these files
+depend on.
+
+## Commit style
+
+- [Conventional commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`,
+  `docs:`, `ci:`, `test:`, `refactor:`).
+- No `Co-Authored-By: Claude` trailer or any other AI-authorship marker on commits or PR
+  descriptions — attribute commits to yourself only.
+
+## PR flow
+
+1. Branch off `main`.
+2. Make your change; keep it additive where possible (see `CLAUDE.md` for the project's
+   architecture and invariants).
+3. Make sure the full local gate above is green.
+4. Open a PR against `main`. CI must pass before merge.
+
+## Questions
+
+Open an issue using the templates in `.github/ISSUE_TEMPLATE/`, or see `SECURITY.md` if
+you're reporting a vulnerability rather than a bug.

tracefork-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pratik Soni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.