spec: issue-3582 Trace evidence export to disk

[matiasinsaurralde]

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]

PR validation — ✅ 3 passing

Status	Policy	Material	Messages
✅ Passed	pr-min-approvals	pr-info	-
✅ Passed	pr-description-required	pr-info	-
✅ Passed	pr-user-story-linked	pr-info	-

_{View attestation ↗}

AI Session Checks — ⚠️ no AI session found

Missing AI Coding Sessions

This organization requires every PR to be backed by a Chainloop Trace AI coding session, and none was found for this one.

Please make sure the AI coding session evidence has been sent by the Chainloop CLI, or add the skip-ai-session label to this PR to bypass this check.

Learn more about Chainloop Trace.

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]

2 issues found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/specs/issue-3582-trace-evidence-export.md">

<violation number="1" location="docs/specs/issue-3582-trace-evidence-export.md:59">
P2: The no-network requirement also covers the first surface, a single-session run that invokes an agent whose model needs network access. Scope R-001 and R-005 to the export/backend phase so the run flag can satisfy the spec.</violation>

<violation number="2" location="docs/specs/issue-3582-trace-evidence-export.md:62">
P2: R-006 does not require the manifest to identify this export as unsigned and not an attestation, so a conforming export can omit the signal its risk mitigation relies on. Require that declaration in the index.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The no-network requirement also covers the first surface, a single-session run that invokes an agent whose model needs network access. Scope R-001 and R-005 to the export/backend phase so the run flag can satisfy the spec.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/specs/issue-3582-trace-evidence-export.md, line 59:

<comment>The no-network requirement also covers the first surface, a single-session run that invokes an agent whose model needs network access. Scope R-001 and R-005 to the export/backend phase so the run flag can satisfy the spec.</comment>

<file context>
@@ -0,0 +1,122 @@
+- Done when: a secret in a spec source does not appear in the exported files.
+
+### R-005: No control plane and no credentials
+The mode MUST NOT need a control plane, an organization, a token, or a network.
+
+### R-006: A manifest
</file context>

[cubic-dev-ai]

P2: R-006 does not require the manifest to identify this export as unsigned and not an attestation, so a conforming export can omit the signal its risk mitigation relies on. Require that declaration in the index.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/specs/issue-3582-trace-evidence-export.md, line 62:

<comment>R-006 does not require the manifest to identify this export as unsigned and not an attestation, so a conforming export can omit the signal its risk mitigation relies on. Require that declaration in the index.</comment>

<file context>
@@ -0,0 +1,122 @@
+The mode MUST NOT need a control plane, an organization, a token, or a network.
+
+### R-006: A manifest
+The mode MUST write an index. The index MUST list each material by name, kind, and digest. A reader MUST see the whole set of materials from the index, with no need to parse each file. The evidence record holds the warnings of the run, not the index.
+
+### R-007: Export from a recorded session
</file context>

Suggested change

	The mode MUST write an index. The index MUST list each material by name, kind, and digest. A reader MUST see the whole set of materials from the index, with no need to parse each file. The evidence record holds the warnings of the run, not the index.
	The index MUST state that this export is unsigned and is not an attestation, and list each material by name, kind, and digest.

[javirln]

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