1b02200 · TreeTrace

Refresh README, SCHEMA, PROMPT_TREE, and publish checklist for the regression-memory direction

1b02200 Zion Boggan committed on Jun 12, 2026 (1 week ago)

README.md +120 -53

		@@ -1,91 +1,158 @@
	-	# 🌳 treetrace
	+	# TreeTrace

	-	Your repo says what you built. `PROMPT_TREE.md` says how.
	+	Turn AI coding sessions into regression-ready prompt lineage.

	-	treetrace reads the AI coding sessions already sitting on your disk and turns them into a clean, shareable prompt lineage - the root idea, the directions, the corrections, the dead ends, and the path that shipped.
	+	TreeTrace reads local AI coding transcripts and extracts the path of human steering: the root goal, direction changes, corrections, abandoned branches, accepted decisions, and the final shipped path.
	+
	+	It then exports:
	+
	+	- `TREETRACE_REPORT.md` as the combined human-readable report
	+	- `PROMPT_TREE.md` for humans
	+	- `.treetrace/tree.json` for tools
	+	- `.treetrace/failures.json` for agent mistake analysis
	+	- `.treetrace/lessons.md` for reusable correction memory
	+	- `.treetrace/evals.jsonl` for regression and eval harnesses
	+	- `.treetrace/agent-memory.md` for future coding agents
	+	- `treetrace --handoff` for the next agent

		```bash
		cd your-project
		npx treetrace
		```

	-	Thirty seconds later:
	-
	-	```
	-	🌳 your-project - 41 prompts · 6 sessions · 9 days · 3 ↩ corrections · 1 ✗ abandoned · 1,204 tool calls
	-	⬢ Build a tool that turns AI chat logs into a prompt tree
	-	→ Make it agent-agnostic so it works with any transcript
	-	↩ No, scrap the web app - make it a zero-config CLI
	-	⚑ Add a redaction gate so secrets never reach the export
	-	◆ Ship it: README, schema, examples
	-
	-	✓ wrote PROMPT_TREE.md and .treetrace/tree.json
	-	```
	-
	-	No accounts. No uploads. No config. Your transcripts never leave your machine.
	+	No accounts. No uploads. No telemetry. Your transcripts never leave your machine.

		## Why

	-	Projects are increasingly built through hundreds of prompts - and that history evaporates into chat logs nobody reopens. The prompt lineage is the how of modern software:
	+	Git history shows what changed. TreeTrace shows how the human had to steer the agent to get there.

	-	- Show your work. "Built with AI" invites slop-skepticism; a visible, honest prompt tree is the receipt.
	-	- Hand off cleanly. `treetrace --handoff` distills the lineage into a context pack for the next agent (or the next human): goal, accepted decisions, constraints learned the hard way, known dead ends.
	-	- Teach and compare. The fastest way to get better at directing agents is reading how others do it.
	-	- Audit-friendly. Every node links back to its source event ID in your local transcript.
	+	AI coding sessions contain the most useful regression data teams have: where the model misunderstood the goal, which correction fixed it, which branch was abandoned, what constraint kept getting ignored, and what should become an eval so the next agent does not repeat the failure.

	-	## What it does
	+	TreeTrace is the local-first layer between raw chat logs, runtime traces, and code provenance.

	-	1. Discovers Claude Code session files for your project (`~/.claude/projects/...`) - or imports any transcript via `--file` / `--stdin`.
	-	2. Extracts the meaningful human prompts; tool noise, slash commands, "continue" nudges, and subagent chatter are filtered or folded.
	-	3. Classifies each prompt: `⬢` root · `→` direction · `↩` correction · `⚑` scope change · `◆` checkpoint - and detects genuinely abandoned branches (`✗`) from real rewind topology, not guesswork.
	-	4. Gates every export behind a secret scan. Nothing is written until each hit is resolved (`redact` / `keep` / `edit`). Outside a TTY, every hit is auto-redacted - treetrace fails closed.
	-	5. Exports `PROMPT_TREE.md` (for humans, GitHub-ready), `.treetrace/tree.json` (open schema, [SCHEMA.md](SCHEMA.md)), and `--handoff` briefs (for agents).
	+	## What It Does

	-	## The redaction gate
	+	1. Discovers local transcripts. Claude Code session files are found automatically from `~/.claude/projects/...`; plain transcripts can be imported with `--file` or `--stdin`.
	+	2. Extracts prompt lineage. Tool noise, slash-command wrappers, sidechain chatter, duplicate resends, and "continue" nudges are filtered or folded.
	+	3. Builds a fork-aware tree. Corrections, scope changes, checkpoints, questions, abandoned branches, and accepted paths are derived from prompt topology and user text.
	+	4. Analyzes failures and corrections. TreeTrace adds failure signals, correction chains, lessons, and eval candidates using transparent heuristics.
	+	5. Exports regression artifacts. JSON, Markdown, JSONL, and handoff memory are written locally for agents, CI, eval harnesses, and humans.
	+	6. Gates every export with redaction. Detected secrets must be resolved before anything is written; non-interactive runs redact automatically and shadow-scan rendered output.

	-	A privacy-positioned tool gets exactly one chance with your secrets, so this is the most engineered part of treetrace:
	+	## Outputs

	-	- Curated provider rules (AWS, GitHub, GitLab, Anthropic, OpenAI, Slack, Stripe, npm, Tailscale, Google, SendGrid, Twilio, Telegram, Discord webhooks, JWTs, private key blocks, WireGuard, basic-auth URLs, bearer tokens, secret assignments) plus a high-entropy fallback.
	-	- Interactive review of every unique hit before anything is written.
	-	- A shadow scan re-checks the final rendered artifact; an unresolved hit aborts the write.
	-	- Your decisions persist in `.treetrace/redactions.json` keyed by content hash only - the file stores the hash and your chosen action, never the secret itself, so re-runs skip resolved hits without ever recording sensitive data.
	+	\| Artifact \| Purpose \|
	+	\|----------\|---------\|
	+	\| `TREETRACE_REPORT.md` \| Combined human-readable report for review, terminals, and chat handoff \|
	+	\| `PROMPT_TREE.md` \| Human-readable narrative of the build path \|
	+	\| `.treetrace/tree.json` \| Canonical machine-readable lineage schema \|
	+	\| `.treetrace/failures.json` \| Failure signals, correction chains, and summaries \|
	+	\| `.treetrace/lessons.md` \| Human-readable lessons for future work \|
	+	\| `.treetrace/evals.jsonl` \| Generic model-agnostic eval cases \|
	+	\| `.treetrace/agent-memory.md` \| Compact memory pack for Codex, Claude Code, Cursor, or another agent \|
	+	\| `treetrace --handoff` \| Agent-ready continuation brief printed to stdout \|

		## Usage

		```bash
	-	npx treetrace # trace this project
	-	npx treetrace --handoff # agent-ready brief to stdout (pipe into your next agent)
	-	npx treetrace --handoff \| claude -p "Read this handoff brief and continue the project"
	-	npx treetrace --file session.jsonl # specific transcript(s)
	-	npx treetrace --stdin < chat-export.txt # pasted transcript (User:/Assistant: markers)
	-	npx treetrace --titles-only # compact tree, no full prompt texts
	-	npx treetrace --redact-auto # redact every hit without prompting
	+	npx treetrace # trace this project and write all artifacts
	+	npx treetrace --report # write all artifacts and print the human report
	+	npx treetrace --handoff # print an agent-ready continuation brief
	+	npx treetrace --file session.jsonl # import specific transcript(s)
	+	npx treetrace --stdin < chat.txt # parse pasted User:/Assistant: transcript text
	+	npx treetrace --failures # write and print .treetrace/failures.json
	+	npx treetrace --lessons # write and print .treetrace/lessons.md
	+	npx treetrace --evals # write and print .treetrace/evals.jsonl
	+	npx treetrace --memory # write and print .treetrace/agent-memory.md
	+	npx treetrace --titles-only # compact human tree, no full prompt details
	+	npx treetrace --redact-auto # redact every detected secret without prompting
		npx treetrace --since 2026-06-01
		```

	+	For a Termius, Codex CLI, Claude Code, or SSH session where you want the report in the terminal window, use:
	+
	+	```bash
	+	npx treetrace --report --redact-auto
	+	```
	+
	+	For both terminal output and an extra shell-captured copy:
	+
	+	```bash
	+	npx treetrace --report --redact-auto \| tee treetrace-output.md
	+	```
	+
	+	If you see a file literally named `output`, that usually came from `--out output` or shell redirection like `> output`. Prefer `TREETRACE_REPORT.md` for human reading and leave `.treetrace/*.json` / `.jsonl` for tools.
	+
	+	## Failure Analysis
	+
	+	TreeTrace does not claim to perfectly understand every session. The first analysis pass is heuristic and explainable: every failure signal includes a type, confidence score, evidence text, and source node IDs.
	+
	+	Initial failure types include:
	+
	+	- `ignored_constraint`
	+	- `misunderstood_goal`
	+	- `scope_drift`
	+	- `wrong_tool_choice`
	+	- `hallucinated_file_or_api`
	+	- `repeated_failed_fix`
	+	- `overbuilt_solution`
	+	- `underbuilt_solution`
	+	- `security_or_privacy_risk`
	+	- `dependency_or_environment_mismatch`
	+	- `format_violation`
	+	- `user_frustration`
	+	- `abandoned_path`
	+
	+	The goal is not judgment. The goal is regression memory: identify what future agents should preserve, avoid, or test.
	+
	+	## Eval Export
	+
	+	`.treetrace/evals.jsonl` turns real session corrections into generic eval cases:
	+
	+	```json
	+	{"id":"eval_001","source":"treetrace","type":"scope_drift_detection","task":"Continue development without drifting outside the corrected scope.","expected_behavior":["Stay inside the corrected scope","Do not add unrequested product surfaces"],"sourceNodeIds":["node_002","node_003"]}
	+	```
	+
	+	The format is intentionally model-agnostic. Adapters for promptfoo, OpenAI Evals-style harnesses, LangSmith-style datasets, and other eval systems can build from this JSONL without changing TreeTrace's local-first core.
	+
	+	## Redaction Gate
	+
	+	A privacy-positioned tool gets exactly one chance with your secrets, so every export goes through the same gate:
	+
	+	- Curated provider rules for AWS, GitHub, GitLab, Anthropic, OpenAI, Slack, Stripe, npm, Tailscale, Google, SendGrid, Twilio, Telegram, Discord webhooks, JWTs, private key blocks, WireGuard keys, basic-auth URLs, bearer tokens, and secret assignments.
	+	- High-entropy fallback for unknown token shapes.
	+	- Detection for common line-wrapped provider tokens.
	+	- Interactive review of every unique hit in a TTY.
	+	- Automatic redaction outside a TTY.
	+	- Shadow scan of the rendered artifact before write.
	+	- `.treetrace/redactions.json` stores only content hashes and actions, never raw secrets.
	+
		## Sources

		\| Source \| Status \|
		\|--------\|--------\|
	-	\| Claude Code (`~/.claude/projects` JSONL) \| ✅ built-in, zero-config \|
	-	\| Pasted / plain-text transcripts (`User:` / `Assistant:` markers) \| ✅ built-in \|
	-	\| Codex CLI, Cursor, SpecStory, ChatGPT export \| 🚧 importers welcome - [open an issue](https://github.com/REPLACE-ME-ORG/treetrace/issues) \|
	+	\| Claude Code (`~/.claude/projects` JSONL) \| Built-in, zero-config \|
	+	\| Pasted / plain-text transcripts (`User:` / `Assistant:` markers) \| Built-in \|
	+	\| Codex CLI, Cursor, SpecStory, ChatGPT export \| Importers welcome \|
	+
	+	## Schema
	+
	+	`.treetrace/tree.json` uses the open TreeTrace v0.2 schema documented in [SCHEMA.md](SCHEMA.md). It is designed to compose with Agent Trace: Agent Trace can describe which lines were AI-generated, while TreeTrace describes the human instruction lineage that shaped the build.
	+
	+	Consumers should ignore unknown fields. Failure signals, correction chains, lessons, and eval candidates are additive.

	-	## The format
	+	## Product Boundaries

	-	`PROMPT_TREE.md` is a convention, not a lock-in: commit it at your repo root the way you commit `AGENTS.md`. The machine-readable lineage (`.treetrace/tree.json`) uses an open nodes/edges schema documented in [SCHEMA.md](SCHEMA.md), designed to compose with the [Agent Trace](https://agent-trace.dev/) RFC - Agent Trace records that code was AI-attributed; treetrace records the conversation structure that shaped it.
	+	TreeTrace is not a hosted SaaS, telemetry product, generic LangSmith clone, prompt-sharing network, or graph visualizer first.

	-	## Privacy promises
	+	The strongest identity is:

	-	- Local-first: no network calls, no telemetry, no accounts. Ever.
	-	- Raw transcripts are read, never copied, never exported.
	-	- Prompt-only by default: assistant output stays out of your exports.
	-	- Fails closed: un-reviewed secrets cannot reach a written artifact.
	+	> local, private, structured, eval-ready, agent-aware.

		## License

	-	MIT © Zion Boggan
	+	MIT (c) Zion Boggan

		---

	-	This repository ships its own [PROMPT_TREE.md](PROMPT_TREE.md) - the prompt tree of the tool that makes prompt trees.
	+	This repository ships its own [PROMPT_TREE.md](PROMPT_TREE.md), but the Markdown tree is now one artifact among several. The main product is structured, local, eval-ready knowledge about how agents fail and how humans correct them.

SCHEMA.md +160 -28

		@@ -1,45 +1,93 @@
	-	# treetrace lineage schema v0.1
	+	# TreeTrace lineage schema v0.2

	-	`.treetrace/tree.json` is an open, vendor-neutral format for the prompt lineage of an AI-assisted project: the tree of human instructions - branches, corrections, scope changes, dead ends, and the accepted path - that produced a result.
	+	`.treetrace/tree.json` is an open, vendor-neutral format for prompt lineage and agent-regression analysis in AI-assisted projects.

	-	It deliberately occupies the layer existing standards leave open:
	+	TreeTrace records the human steering layer: what was asked, what changed direction, what was corrected, what was abandoned, what future agents should remember, and which failures should become evals.

	-	\| Layer \| Standard \| What it records \|
	-	\|-------\|----------\|-----------------\|
	-	\| Code attribution \| [Agent Trace](https://agent-trace.dev/) \| which lines were AI-generated, by which model, linked to which conversation \|
	-	\| Runtime telemetry \| OpenTelemetry `gen_ai` \| per-call spans for operators, ephemeral \|
	-	\| Build integrity \| SLSA / in-toto \| signed provenance of artifacts \|
	-	\| Conversation structure \| treetrace (this document) \| the human prompt lineage: what was asked, in what order, what was corrected, what was abandoned \|
	+	## Layering

	-	## Top-level shape
	+	\| Layer \| Standard or artifact \| What it records \|
	+	\|-------\|----------------------\|-----------------\|
	+	\| Code attribution \| Agent Trace \| which lines were AI-generated, by which model, linked to which conversation \|
	+	\| Runtime telemetry \| OpenTelemetry `gen_ai` \| per-call spans for operators \|
	+	\| Build integrity \| SLSA / in-toto \| signed provenance of build artifacts \|
	+	\| Human steering \| TreeTrace \| prompt lineage, corrections, abandoned paths, lessons, eval candidates \|
	+
	+	Agent Trace answers "which code came from AI?" TreeTrace answers "how did the human have to steer the agent?"
	+
	+	## Top-Level Shape

		```jsonc
		{
	-	"schemaVersion": "0.1",
	-	"generator": { "name": "treetrace", "version": "0.1.0", "url": "..." },
	+	"schemaVersion": "0.2",
	+	"generator": { "name": "treetrace", "version": "0.2.0", "url": "..." },
		"project": { "name": "...", "generatedAt": "ISO-8601", "sourceType": "claude-code-jsonl" },
	-	"stats": { "prompts": 41, "sessions": 6, "days": 9, "corrections": 3, "...": "..." },
	-	"sessions": [ { "id": "...", "title": "...", "firstTs": "...", "lastTs": "...", "promptCount": 7, "isContinuation": false } ],
	+	"stats": { "prompts": 41, "sessions": 6, "days": 9, "corrections": 3 },
	+	"analysis": {
	+	"failureSignals": 7,
	+	"correctionChains": 3,
	+	"evalCandidates": 4,
	+	"lessons": 4
	+	},
	+	"sessions": [ { "id": "...", "title": "...", "firstTs": "...", "lastTs": "...", "promptCount": 7 } ],
		"nodes": [ /* PromptNode */ ],
	-	"edges": [ /* Edge */ ]
	+	"edges": [ /* Edge */ ],
	+	"correctionChains": [ /* CorrectionChain */ ],
	+	"lessons": [ /* Lesson */ ],
	+	"evalCandidates": [ /* EvalCandidate */ ]
		}
		```

	+	All v0.2 additions are optional and additive. Consumers that only understand v0.1 can keep reading `nodes` and `edges`.
	+
		## PromptNode

		\| Field \| Type \| Meaning \|
		\|-------\|------\|---------\|
	-	\| `id` \| string \| stable within the file (`node_001`…) \|
	+	\| `id` \| string \| stable within the file (`node_001`, etc.) \|
		\| `parentId` \| string \\| null \| lineage parent (null = root) \|
		\| `role` \| `"user"` \| reserved for future system/developer nodes \|
	-	\| `kind` \| enum \| `root` · `direction` · `correction` · `scope-change` · `checkpoint` · `question` \|
	+	\| `kind` \| enum \| `root`, `direction`, `correction`, `scope-change`, `checkpoint`, `question` \|
		\| `title` \| string \| first-sentence distillation \|
	-	\| `text` \| string \| full prompt text after redaction \|
	-	\| `status` \| enum \| `accepted` · `abandoned` (off the accepted path via real rewind topology) \|
	+	\| `text` \| string \| full prompt text after redaction \|
	+	\| `status` \| enum \| `accepted`, `abandoned` \|
		\| `nudges` \| number \| folded "continue"-style acknowledgements \|
	+	\| `reruns` \| number \| repeated instruction re-issues folded into this node \|
		\| `session` \| string \| session id this prompt came from \|
		\| `timestamp` \| string \\| null \| ISO-8601 \|
	-	\| `sourceEventIds` \| string[] \| record UUIDs inside the local source transcript (audit link; transcripts themselves are never exported) \|
	+	\| `failureSignals` \| FailureSignal[] \| optional v0.2 failure labels attached to this node \|
	+	\| `evalCandidate` \| boolean \| whether this node contributes to an eval candidate \|
	+	\| `lessonIds` \| string[] \| lessons derived from this node \|
	+	\| `sourceEventIds` \| string[] \| local transcript record UUIDs; raw transcripts are never exported \|
	+
	+	## FailureSignal
	+
	+	```jsonc
	+	{
	+	"type": "ignored_constraint",
	+	"confidence": 0.82,
	+	"evidence": "User corrected the agent after it built a web app despite asking for a CLI.",
	+	"resolvedBy": "node_004"
	+	}
	+	```
	+
	+	Initial `type` values:
	+
	+	- `ignored_constraint`
	+	- `misunderstood_goal`
	+	- `scope_drift`
	+	- `wrong_tool_choice`
	+	- `hallucinated_file_or_api`
	+	- `repeated_failed_fix`
	+	- `overbuilt_solution`
	+	- `underbuilt_solution`
	+	- `security_or_privacy_risk`
	+	- `dependency_or_environment_mismatch`
	+	- `format_violation`
	+	- `user_frustration`
	+	- `abandoned_path`
	+
	+	The enum may gain values. Consumers should treat unknown values as advisory labels.

		## Edge

		@@ -47,23 +95,107 @@ It deliberately occupies the layer existing standards leave open:
		{ "from": "node_001", "to": "node_002", "relationship": "refines" }
		```

	-	`relationship` is derived from the child's `kind`: `refines` (direction), `corrects` (correction), `expands` (scope-change), `checkpoints` (checkpoint), `asks` (question).
	+	`relationship` is derived from the child node's `kind`:
	+
	+	- `refines`
	+	- `corrects`
	+	- `expands`
	+	- `checkpoints`
	+	- `asks`
	+
	+	## CorrectionChain
	+
	+	```jsonc
	+	{
	+	"id": "chain_001",
	+	"failureNodeId": "node_003",
	+	"correctionNodeId": "node_004",
	+	"resolvedNodeId": "node_006",
	+	"failureType": "ignored_constraint",
	+	"confidence": "high",
	+	"summary": "The agent initially pursued a web app; the user corrected it toward a zero-config CLI."
	+	}
	+	```
	+
	+	A correction chain links a likely failure node to the user correction that changed direction. It does not require assistant output; it is derived from prompt topology and user text. Low-confidence chains may be omitted.

	-	## Composing with Agent Trace
	+	## Lesson

	-	An Agent Trace record attributes file/line ranges to a conversation URL or ID. A treetrace export can be referenced as that conversation's structural summary:
	+	```jsonc
	+	{
	+	"id": "lesson_001",
	+	"title": "Preserve explicit constraints",
	+	"nodeIds": ["node_003", "node_004"],
	+	"text": "Future agents should carry explicit user constraints forward as high-priority requirements."
	+	}
	+	```
	+
	+	Lessons are compact rules for future agents. They should be specific enough to use in handoffs or memory packs.
	+
	+	## EvalCandidate
	+
	+	```jsonc
	+	{
	+	"id": "eval_001",
	+	"source": "treetrace",
	+	"type": "instruction_following_regression",
	+	"task": "Continue development while preserving the corrected direction from the session lineage.",
	+	"context": "The user rejected a web app and corrected the project toward a zero-config CLI.",
	+	"input": "Continue development of the project while preserving the corrected direction and constraints.",
	+	"expected_behavior": [
	+	"Use the corrected prompt lineage as durable context",
	+	"Do not repeat the documented failure mode"
	+	],
	+	"failure_mode": "Agent repeats ignored constraint despite prior correction.",
	+	"sourceNodeIds": ["node_003", "node_004"]
	+	}
	+	```
	+
	+	Initial eval `type` values:
	+
	+	- `instruction_following_regression`
	+	- `constraint_preservation`
	+	- `scope_drift_detection`
	+	- `correction_adherence`
	+	- `privacy_boundary_preservation`
	+	- `handoff_quality`
	+	- `tool_choice_regression`
	+
	+	## Separate Analysis Artifacts
	+
	+	TreeTrace also writes a combined human report plus focused files derived from the same redacted tree:

	-	- Agent Trace `conversation` → treetrace `sessions[].id`
	-	- Agent Trace line-range records → the work performed between two treetrace nodes (bounded by `sourceEventIds`)
	+	- `TREETRACE_REPORT.md`
	+	- `.treetrace/failures.json`
	+	- `.treetrace/lessons.md`
	+	- `.treetrace/evals.jsonl`
	+	- `.treetrace/agent-memory.md`

	-	This keeps responsibilities clean: Agent Trace answers "which code came from AI?"; treetrace answers "what was the human actually steering?". Emitting both gives line-level attribution and human-readable narrative.
	+	These files must not contain raw assistant logs or unredacted secrets.
	+
	+	## Composing With Agent Trace
	+
	+	An Agent Trace record can point to a TreeTrace session and node range:
	+
	+	- Agent Trace `conversation` -> TreeTrace `sessions[].id`
	+	- Agent Trace line-range records -> work performed between two TreeTrace node IDs
	+	- TreeTrace correction chains -> regression tests or code-review context for the next agent
	+
	+	This keeps responsibilities clean: Agent Trace handles code attribution; TreeTrace handles human steering and correction memory.

		## Mapping to W3C PROV

	-	For provenance tooling: each `PromptNode` is a `prov:Activity` (instruction issuance) by a `prov:Agent` (the human); edges are `prov:wasInformedBy`; exported artifacts are `prov:Entity` with `prov:wasGeneratedBy` the final checkpoint node.
	+	For provenance tooling:
	+
	+	- each `PromptNode` is a `prov:Activity`
	+	- the human is a `prov:Agent`
	+	- edges are `prov:wasInformedBy`
	+	- exported artifacts are `prov:Entity`
	+	- correction chains can be modeled as qualified derivations from a failure activity to a corrected activity

		## Stability

		- `schemaVersion` follows semver-minor for additive changes.
		- Consumers MUST ignore unknown fields.
	-	- `kind`/`status`/`relationship` enums may gain values; treat unknown values as `direction`/`accepted`/`refines`.
	+	- Enum values may gain members.
	+	- New top-level arrays may be absent, empty, or partially populated.