Skip to main content

ADR-0011: Trajectories as First-Class Versioned Artifacts

Framed by ADR-0019: trajectories are the substrate of Stet's compounding project memory posture, and the "trajectories are software artifacts" framing below is promoted there to a user-facing trust principle — the agent's reasoning is a file in your repo, not a black box. The committed trajectory is also the primary graduation target for the in-session inner loop (ADR-0020).

Status​

Proposed / exploring. Captured during ideation on 2026-07-04; several internal directions were decided in review the same day (marked DECIDED below). Paired with ADR-0012 (skill distillation). Revisit for promotion to accepted (+ a spec) after the core loop (SPEC-0001..0003) is standing.

Context and Problem Statement​

When Stet dispatches an agent (SPEC-0003), the agent produces a trajectory: the ordered record of everything it did — the seeding brief, its reasoning, tool calls, the diffs it produced, cost, and outcome. Today that record is ephemeral: SPEC-0003 streams a live transcript for viewing and then discards it.

The idea: make the trajectory a persisted, structured, versioned artifact that lives inside the repository, alongside the code it produced, and is reviewed the same way as any file (ADR-0002 canvas, ADR-0008 tour). Trajectories become the provenance layer of the whole system and the raw material for skill distillation (ADR-0012).

Framing — trajectories are software artifacts​

The governing principle (per review): a trajectory is not a log, it is part of the project's software. It is committed, versioned, reviewed, diffed, and — like source — subjected to deterministic tooling (secret-scanning, redaction, schema validation) before it lands. The schema is open, versioned, and documented so the artifacts are portable and not Stet lock-in. The same principle governs skills (ADR-0012).

Decisions​

DECIDED — Storage: committed files under .stet/​

Trajectories are committed as plain, diff-friendly files under a .stet/ area in the repo (alongside skills/ and feedback/ per ADR-0012). Canonical form is a JSONL stream of normalized events (from the TranscriptEvent stream, SPEC-0003) + a rendered Markdown narration for reading + a metadata header (brief reference, model/harness/runtime, diffs produced, cost, timing, feedback that seeded it).

Rejected alternatives: git notes (refs/notes/stet) — provenance without tree noise, but poor "review like a file" UX and notes are rarely fetched/rewritten safely; orphan branch / separate refs — keeps main clean but breaks "sits alongside the code." Both undercut the two properties that matter most (reviewable as a file; travels with the repo).

DECIDED — SHA coupling: trajectory is the branch's final commit​

A trajectory that produced commit X cannot sit inside X without changing X's hash. Resolution: commit the trajectory as the branch's final commit, describing the work up to its parent. The trajectory therefore lives in the same branch/PR as the code it produced, references the parent it built upon, and is reviewed as the last "stop" of that change. (Content-addressing was considered and set aside; this ordering gives cleaner provenance — the trajectory is literally the capstone of the branch.)

DECIDED — Audio: transcript in-repo, raw audio opt-in via LFS​

The committed artifact is the transcript (deterministic text — diffable, scannable, reviewable). Raw audio is not committed by default; it is treated as the source of the transcript and kept out of git (optional local cache). Users who want to retain original recordings can opt in to audio retention via Git LFS (pointer in repo, bytes in the host's LFS store). Keeps .stet/ text-first.

DECIDED — Privacy gate: static, deterministic, bundled​

Trajectories capture file contents, tool output, model reasoning, and can capture secrets — and they may be committed into public repos (the stet repo itself is public). Therefore, before any trajectory is written to disk/committed:

  • Stet bundles one or more OSS secret scanners (candidates with bundle-friendly licenses: gitleaks — MIT; detect-secrets — Apache-2.0; trufflehog is more powerful but AGPL, so license diligence is required before bundling) and runs them as a mandatory, blocking gate.
  • Redaction is static and deterministic (rule-based, reproducible) — not model-based — so the same trajectory always redacts identically and the pipeline is auditable.
  • A .stetignore lets a project exclude paths/patterns from capture.
  • The default posture is safe-by-default, with extra caution surfaced when the target repo is public.

Review UX​

A trajectory canvas mode and an Anchor.trajectoryStep case (extending ADR-0002/0008). A trajectory reads like a tour of what the agent did; the human marks it up ("this step was wrong", "this was clever"), and that markup becomes distillation fuel (ADR-0012) and can seed a follow-up dispatch (ADR-0006).

Why it fits​

  • Good, because provenance becomes durable, local, and versioned — far richer than Co-Authored-By, owned by the repo, not a vendor.
  • Good, because it reuses the transcript stream (SPEC-0003), the canvas (ADR-0002), and tour rendering (ADR-0008).
  • Good, because it is the necessary substrate for ADR-0012 (no kept trajectories → nothing to distill).

Open questions​

  • Trajectory schema — exact open, versioned format (JSONL event vocabulary + metadata header + rendered narration) and how it evolves.
  • Retention & size policy (keep for merged PRs, prune abandoned) and defaults.
  • Redaction rule set — the concrete deterministic rules beyond secret-scanning (paths, env, tokens) and how projects extend them via .stetignore.
  • Trajectories are records, not replays — nondeterministic models; clarify they are not guaranteed reproducible.

Consequences (tentative)​

  • Adds a Trajectory artifact + open schema, a .stet/ storage convention, a canvas mode, and an Anchor.trajectoryStep case.
  • Introduces a bundled, deterministic secret-scan + redaction subsystem that MUST run before any trajectory is committed — a hard dependency, not optional.
  • Establishes the input contract consumed by ADR-0012.

More Information​

Paired with ADR-0012 (skill distillation). Shared theme: the project learns over time; provenance is a first-class, versioned software artifact.