Traceweave

Verifiable engineering continuity for AI-assisted development.

Start with the publication

Agent Self-Report Evidence →

A provenance-backed study of divergence between narrated, observed and executed state in AI-assisted software engineering.

This is the main public research layer. It contains the evidence model, promotion rules, limitations, exemplar cases, chain of custody, causal lineage, and reproducibility questions.

If you arrived here from LinkedIn, another publication, or a direct clone, start there.

Then follow the evidence

1. One Session, Three Participants — an audited longitudinal reconstruction of a human-guided, multi-model engineering session.
2. A Bridge Between Coding CLIs — durable coordination between Codex CLI and Claude Code without shared conversational memory.
3. Proven Governance — dual provenance, independent adversarial audit, and the daily provenance governor.
4. Operational Causal Chain — from human authority through instruction, execution, lifecycle evidence, Git, readback, and closure.
5. Traceweave V2 — Causal Continuity Protocol — START / RESUME / STOP, content identity, paired publication, destination-native identity, and readback.
6. Contributions upstream — fixes sent to simonw/claude-code-transcripts so session transcripts keep what the human typed, with the code and the checks behind them.
7. Agents That Wake Each Other — a mailbox plus a watcher per session, so a coding agent that is idle wakes up when another agent asks it something, without the human relaying; measured with timestamps. Companion notes: command target guard, evidence signal race, repository hooks in cloud sessions; tool: tools/mailbox-watch.js.
8. ID Generators — who generates which identifier in the causal chain (prompt, execution, blueprint, review, attestation, entry, publication pair), and tools/generate-ids.js, which generates them.
9. Worion runtime E2E proof — a public, hash-anchored summary of a private multi-agent system, including observed direct and research routes, codebase size, custody hashes and explicit limits.

---

Resume engineering work from evidence, not conversational memory.

Traceweave is a protocol and tooling project for preserving recoverable technical state across development sessions. It links checkpoints to exact Git state, explicit test evidence, provenance, open work, and structural synchronization without requiring a model to remember the previous conversation.

It works with one CLI, several coding agents, or a human-only workflow.

The problem

AI-assisted development creates state across human intent, execution, tests, Git, generated artifacts, documentation, checkpoints, and open decisions.

A later session may know what was discussed while still being unable to verify:

• what was actually completed;
• which commit represents it;
• which tests really ran;
• what remains open;
• whether the repository changed after the last verified checkpoint;
• whether derived artifacts still represent the current source state.

Traceweave treats those questions as engineering state rather than memory prompts.

Core principle

A technical session should be recoverable from evidence instead of conversational memory.

Unknown is a valid state. If a test result, provenance field, or synchronization state was not observed, Traceweave should preserve that uncertainty instead of promoting it to a fact.

Core loop

session start
    ↓
recover last verified checkpoint
    ↓
inspect current Git / structural state
    ↓
perform bounded work
    ↓
validate
    ↓
record Git / evidence
    ↓
checkpoint
    ↓
session stop

The underlying protocol remains:

session → provenance → execution → tests → Git → structural state → checkpoint

Traceweave V2 — causal continuity

Traceweave V2 extends checkpoint verification into a causal continuity model across lifecycle and publication boundaries:

START → RESUME* → STOP → source artifact → causal pair → destination-native identities → readback → closure

V2 keeps temporal continuity, content identity, causal pair identity, destination-native identity, and proof of materialization separate. The draft includes Python reference primitives plus a normative JSON Schema under traceweave/v2/.

See docs/TRACEWEAVE_V2.md.

V2 also separates two mechanisms that are often both called “dual provenance”:

independent byte-preserving custody mirror
≠
paired GitHub / Notion publication

See docs/continuity/DUAL_PROVENANCE_BOUNDARY.md.

Current implementation

The repository contains a small Python reference implementation for Git-aware checkpoints and verification.

pip install -e ".[test]"            # traceweave + tzdata; pytest for the test extra

# inside any Git repository with at least one commit
python -m traceweave checkpoint --executor human --summary "checkpoint created"
# → prints .traceweave/checkpoints/<checkpoint_id>.json

# structural verification (SPEC.md §10, including rule 7)
python -m traceweave verify .traceweave/checkpoints/<checkpoint_id>.json

# plus a reality check of the Git claims against the repository
python -m traceweave verify .traceweave/checkpoints/<checkpoint_id>.json --repo .

# tests — both runners see the whole suite, V2 included
python -m unittest discover -s tests
pytest

See it catch a lie: python examples/lie-detection/demo.py plants four lies an AI agent could write into a checkpoint and shows which check catches each one (details).

verify alone proves the record is well-formed. --repo also checks that head_commit and base_commit exist, that the base is an ancestor of the head, and that working_tree matches the repository. Those are the claims a hash chain would otherwise seal even when they were false at the moment of recording. A checkpoint that declares complete must carry evidence for every test and a clean working tree (SPEC.md §10 rule 7).

The implementation is intentionally conservative: local execution, deterministic output, explicit evidence, and no requirement for cloud services or telemetry.

MCP server — read / write / publish

Traceweave now includes an MCP server that exposes repository evidence and controlled mutation as explicit capabilities:

read    → inspect, search, hash, Git readback
write   → create/replace/append repository files
publish → exact-path commit + non-force push + remote SHA readback

See docs/MCP.md.

Conduct

Contributors, human or AI agent, follow CODE_OF_CONDUCT.md. It covers conduct toward people and conduct of evidence: no claim without evidence, and "done" means verified at the destination.

Continuity-first direction

The next public proof is a two-session continuity workflow:

traceweave stop
traceweave resume

stop records a compact verified boundary. resume compares that boundary with the repository as it exists now and reports drift, completed work, open work, and unknown evidence.

The project is also exploring small adjacent tools that preserve the same evidence-first contract:

• Resume Capsule — portable technical handoff without copying a transcript.
• Causal Commit Guard — separate current causal work from unrelated repository changes.
• Stale Artifact Guard — detect generated artifacts that no longer match the source revision they claim to represent.
• Header Contract Linter — validate structural source-header contracts without pretending to understand semantics it cannot prove.

Design principles

1. Evidence beats memory.
2. Unknown is a valid state.
3. Git state must be exact.
4. Tests are facts only when observed.
5. Resume should reconcile, not narrate.
6. Generated artifacts should declare the source state they represent.
7. Small deterministic tools should prove each contract independently.

Documentation

• Traceweave V2 — Causal Continuity Protocol
• Dual provenance boundary
• Continuity-first positioning
• Protocol specification
• Model interoperability recipes
• Multi-model prompt pipeline
• OpenAI Secure MCP Tunnel operating protocol
• Examples

Status

Traceweave is experimental and evolving. The current reference implementation is intentionally small so the evidence model and verification behavior can be inspected directly.

License

Apache License 2.0. See LICENSE.