spec: issue-3582 Trace evidence export to disk by matiasinsaurralde · Pull Request #3583 · chainloop-dev/chainloop

matiasinsaurralde · 2026-10-09T00:59:28Z

Summary

Chainloop Trace assembles a session's evidence on a git push and uploads a signed attestation to the control plane. This spec adds a mode that runs the same assembly and writes the result to a local directory, with no control plane and no attestation. Developers and tests then get the exact evidence a push would produce, on disk, for inspection and comparison. The export writes the evidence record and each material under its content digest, with a manifest.

Open questions for reviewers: none.

We would like two reviewers to approve this spec before it merges.

Refs #3582

Drafted with the br:eng-spec skill (Claude Code).

chainloop-platform · 2026-10-09T00:59:36Z

PR validation — ⚠️ 1 failing

Status	Policy	Material	Messages
⚠️ Failed	`pr-min-approvals`	`pr-info`	PR/MR spec: issue-3582 Trace evidence export to disk #3583 has 0 approving reviews, 1 required. PR/MR spec: issue-3582 Trace evidence export to disk #3583 has unresolved change requests from: ["migmartri"]. Requested changes must be addressed and the review re-submitted.
✅ Passed	`pr-description-required`	`pr-info`	-
✅ Passed	`pr-user-story-linked`	`pr-info`	-

_{View attestation ↗}

AI Session Checks — 🟢 89% · ✅ 0 failing

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 89%	1	✅ 0	100% AI / 0% Human	1	+74 / -43	30h28m20s

🟢 89% — 100% AI — ✅ All policies passing

Oct 11, 2026 21:43 UTC · 30h28m20s · $113.37 · 1.1k in / 722.2k out · claude-code 2.1.296 (claude-opus-4-8)

_{View session details ↗}

Change Summary

Revises the trace-export spec on the spec branch and records implementation decisions.
Adds trace init --local, trace export, and per-clone local-trace behavior on the implementation branch.
Updates the export manifest to declare unsigned, non-attestation output.
Adds and runs targeted command, action, and trace-state tests plus local-mode smoke checks.

AI Session Overall Score

🟢 89% — Strong execution and verification; only planning rigor lagged the task's size.

AI Session Analysis Breakdown

🟢 95% · user-trust-signal

No notes.

🟢 92% · alignment

🟢 AI kept branch, commit, and push constraints explicit before acting. · High Impact

🟢 91% · solution-quality

🟢 AI preserved the real crafter path instead of introducing a digest shortcut. · High Impact

🟢 90% · verification

🟢 AI repeatedly built, tested, and smoke-checked the affected trace paths. · High Impact

🟢 88% · scope-discipline

No notes.

🟡 68% · context-and-planning

🟠 The AI handled a multi-branch feature without a visible written plan, TODO list, or ExitPlanMode step. · Medium Severity

💡 For multi-file work, write a short visible plan before editing so branch switches and milestones stay explicit.

File Attribution

████████████████████ 100% AI / 0% Human

Status	Attribution	File	Lines
modified	ai	`docs/specs/issue-3582-trace-evidence-export.md`	+74 / -43

Policies (4)

Status	Policy	Material	Messages
✅ Passed	`ai-config-ai-agents-allowed`	`ai-coding-session-d139ac`	-
✅ Passed	`ai-config-no-dangerous-commands`	`ai-coding-session-d139ac`	-
✅ Passed	`ai-config-no-secrets`	`ai-coding-session-d139ac`	-
✅ Passed	`ai-config-mcp-servers-allowed`	`ai-coding-session-d139ac`	-

Security Checks — ✅ 5 passing

✅ `secret-scan`

Status	Policy	Messages
✅ Passed	`secrets-detection`	-

✅ `sast-scan`

Status	Policy	Messages
✅ Passed	`owasp-top10-2025`	-
✅ Passed	`sast`	-
✅ Passed	`cwe-top25`	-
✅ Passed	`cwe-top26-40-cusp`	-

Scans not applied (3)

Scan	Reason
`vulnerability-scan`	no manifest/lockfile changed
`github-actions-scan`	no workflow files changed
`iac-scan`	no IaC files changed

_{View attestation ↗}

Security context

✅ Nothing this change touches has a recorded security-fix history.

_{View in Chainloop ↗ · How this works ↗}

Powered by Chainloop and Chainloop Trace

cubic-dev-ai

All reported issues were addressed across 1 file

_{Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic}

javirln · 2026-10-09T10:53:41Z

Do you think we should encrypt the sessions at rest on disk?

migmartri

How does the UX look like? What flags? Does it require init? Can you init without server? Init today requires authentication

migmartri

please review the UX from the POV of seting it up offline

Design spec for a mode that runs the trace push-time assembly and writes the AI coding session evidence set to a local directory, with no control plane and no attestation. Refs #3582 Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

Revise the design so trace init --local is the primary enabling surface, which records a reserved local organization and a repository project so the setup contacts no control plane. trace run --export then wraps the agent and writes the evidence set to disk when the session ends, with no push. Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

Record the decisions the implementation settled. Local mode is marked per-clone in the trace state rather than in the shared repository config. The pre-push hook sends no attestation in local mode. A standalone trace export command writes the evidence of the sessions the hooks already recorded. Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

Scope R-001 and R-005 to the export phase, so a run that wraps the agent does not fall foul of the no-network requirement. Require the index to declare the export is unsigned and not an attestation. Replace the ambiguous "the mode" in the prose with "the export". Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

cubic-dev-ai

All reported issues were addressed across 1 file (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

View guided diff | Re-trigger cubic}

R-008, the summary, and the proposal read as though the push wrote the evidence to disk. State that the hook only skips attestation and writes nothing, and that the separate trace export command writes the evidence on demand. Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

migmartri · 2026-10-13T13:24:27Z

+
+## Goals and Non-Goals
+- Goal: `trace init --local` sets up the repository for local mode and contacts no control plane.
+- Goal: `trace run --export` runs the full push-time assembly and writes the result to a local directory when the session ends. It needs no control plane and does no push.


trace run is for another kind of command, it's for single time runs.

what about extending the current pre-push command?

chainloop trace hook git Handle git hook invocations Usage: chainloop trace hook git [command] Available Commands: commit-msg Handle the commit-msg git hook post-commit Handle the post-commit git hook post-rewrite Handle the post-rewrite git hook pre-push Handle the pre-push git hook

migmartri · 2026-10-13T13:27:12Z

+
+# Spec issue-3582: Trace evidence export to disk
+
+## Summary


I feel this spec is confusing, this is not about exporting evidence to disk, is about adding tracing without cp dependency, as in local.

I'd like this spec to focus on that use case

You initialize a repo, but you indicate that's local, providing optionally a path to where the session will be

When you run the harness, i.e claude, you get told that the session will eb recorded by trace and stored in path

when you push the change, you'll get a message of where it is stored

This has nothing to do with exporting an existing session, this could come in another spec

What do you think?

matiasinsaurralde requested a review from a team October 9, 2026 00:59

cubic-dev-ai Bot reviewed Oct 9, 2026

View reviewed changes

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

matiasinsaurralde mentioned this pull request Oct 9, 2026

feat(trace): export session evidence to disk #3584

Draft

javirln previously approved these changes Oct 9, 2026

View reviewed changes

migmartri reviewed Oct 9, 2026

View reviewed changes

migmartri requested changes Oct 11, 2026

View reviewed changes

matiasinsaurralde force-pushed the issue-3582-spec-trace-evidence-export branch from c468abc to 0901286 Compare October 11, 2026 21:41

jiparis reviewed Oct 12, 2026

View reviewed changes

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

matiasinsaurralde added 2 commits October 13, 2026 00:52

matiasinsaurralde dismissed javirln’s stale review via 10efd4d October 13, 2026 04:02

cubic-dev-ai Bot reviewed Oct 13, 2026

View reviewed changes

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

migmartri reviewed Oct 13, 2026

View reviewed changes

Conversation

matiasinsaurralde commented Oct 9, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

chainloop-platform Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR validation — ⚠️ 1 failing

AI Session Checks — 🟢 89% · ✅ 0 failing

🟢 89% — 100% AI — ✅ All policies passing

Change Summary

AI Session Overall Score

AI Session Analysis Breakdown

🟢 95% · user-trust-signal

🟢 92% · alignment

🟢 91% · solution-quality

🟢 90% · verification

🟢 88% · scope-discipline

🟡 68% · context-and-planning

File Attribution

Policies (4)

Security Checks — ✅ 5 passing

✅ secret-scan

✅ sast-scan

Security context

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

javirln commented Oct 9, 2026

Uh oh!

migmartri left a comment

Choose a reason for hiding this comment

Uh oh!

migmartri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

migmartri Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

migmartri Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

matiasinsaurralde commented Oct 9, 2026 •

edited by cubic-dev-ai Bot

Loading

chainloop-platform Bot commented Oct 9, 2026 •

edited

Loading

✅ `secret-scan`

✅ `sast-scan`

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading