spec: 002 Spec capture for AI coding sessions

[jiparis]

This PR contains a design spec only. It changes no code. Please review the design before the implementation PR.

Summary

An AI coding session record shows what the agent changed, but not what the user asked for. Spec 002 adds the spec of the session to its evidence. At session start, the trace hook tells the agent to write each source that sets the task into a session folder. At push time, the CLI stores each file as its own EVIDENCE material in the attestation. The session material keeps only references to these materials. The same capture works for Claude Code, Cursor and OpenCode.

Open questions for reviewers

• Do Cursor and OpenCode keep the bytes of a pasted image in their transcripts? A later version needs them to store real images.
• Do we add one shared skill that holds the long instruction text?

AI assistance

Claude Code helped to write this spec.

[chainloop-platform]

AI Session Checks — 🟢 84% · ⚠️ 1 failing

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 84%	1	⚠️ 1	97% AI / 3% Human	34	+2985 / -225	144h53m53s

🟢 84% — 97% AI — ⚠️ 1 policies failing

Sep 24, 2026 12:13 UTC · 144h53m53s · $127.49 · 1.5k in / 573.9k out · claude-code 2.1.281 (claude-opus-5-5)

View session details ↗

Change Summary

• Adds spec capture across agent hooks, session-state handling, and OpenCode plugin behavior.
• Stores spec files as redacted EVIDENCE materials referenced by digest and chainloop.spec.* annotations.
• Extends parsing, schema, redaction caching, orphan GC, and review-driven fixes around spec evidence handling.

AI Session Overall Score

🟢 84% — Strong session, but the attestation path still lacks one real end-to-end push.

AI Session Analysis Breakdown

🟢 92% · user-trust-signal

🟢 The user kept giving follow-up tasks instead of restarting or abandoning. · High Impact

🟢 90% · scope-discipline

No notes.

🟢 88% · alignment

No notes.

🟢 84% · solution-quality

No notes.

🟢 82% · context-and-planning

🟢 The code phase started from a user-approved PRD and spec. · High Impact

🟡 74% · verification

🟢 The AI ran repeated go build, go test, lint, and schema checks. · High Impact

🟠 No full trace push against a control plane ran before the PR opened. · Medium Severity

💡 For attestation-path changes, run one real push before merge or block on that gap.

🟡 The user never explicitly confirmed the end-to-end attestation output. · Low Severity

---

File Attribution

███████████████████░ 97% AI / 3% Human

Status	Attribution	File	Lines
modified	ai	app/cli/internal/trace/spec/spec_test.go	+317 / -8
modified	ai	app/cli/pkg/action/trace_spec_materials.go	+289 / -9
modified	ai	app/cli/pkg/action/trace_spec_materials_test.go	+280 / -8
modified	ai	app/cli/internal/trace/spec/spec.go	+262 / -11
modified	ai	app/cli/internal/trace/spec/parse_test.go	+157 / -3
modified	ai	app/cli/internal/trace/spec/parse.go	+134 / -2
modified	ai	app/cli/pkg/action/trace_spec_test.go	+127 / -0
modified	ai	app/cli/pkg/action/trace_hook_handler.go	+73 / -47
created	ai	app/cli/internal/trace/cursor/announce_test.go	+100 / -0
created	ai	app/cli/internal/trace/opencode/announce_test.go	+100 / -0
modified	ai	internal/schemavalidators/schemavalidators_test.go	+97 / -0
modified	ai	pkg/attestation/crafter/materials/aicodingsession/aicodingsession.go	+76 / -13
modified	ai	app/cli/pkg/action/trace_agent_hook_test.go	+88 / -0
created	ai	pkg/attestation/crafter/materials/aicodingsession/spec_test.go	+87 / -0
modified	human	app/cli/internal/trace/claude/announce_test.go	+86 / -0
modified	ai	app/cli/pkg/action/trace_spec.go	+81 / -4
modified	ai	app/cli/pkg/action/trace_banner_test.go	+50 / -19
modified	ai	app/cli/internal/trace/opencode/hooks.go	+41 / -10
modified	ai	app/cli/internal/trace/opencode/testdata/plugin_full.ts	+41 / -10
modified	ai	app/cli/internal/trace/opencode/testdata/plugin_tracerun.ts	+41 / -10
modified	ai	app/cli/internal/trace/state/state_test.go	+50 / -0
modified	ai	app/cli/internal/trace/providers/capabilities_test.go	+27 / -21
modified	ai	pkg/attestation/crafter/materials/aicodingsession/redact_test.go	+47 / -0
modified	ai	app/cli/pkg/action/trace_agent_hook.go	+33 / -13
modified	ai	app/cli/internal/trace/provider.go	+38 / -7

…and 9 more file(s).

---

Policies (4, 1 failing)

Status	Policy	Material	Messages
✅ Passed	ai-config-ai-agents-allowed	ai-coding-session-fd4e67	-
✅ Passed	ai-config-no-dangerous-commands	ai-coding-session-fd4e67	-
⚠️ Failed	ai-config-no-secrets	ai-coding-session-fd4e67	Secret (aws-access-token) detected in session content [turn=850, source=tool_result, line=229]: assert.Contains(t, string(got), "[REDACTED:aws-access-token]") Secret (github-pat) detected in session content [turn=1935, source=assistant-tool_use:Bash, line=52]: assert.Equal(t, "the token [REDACTED:github-pat] fails", got) Secret (github-pat) detected in session content [turn=2064, source=assistant-tool_use:Bash, line=182]: assert.Equal(t, "the token [REDACTED:github-pat] fails", string(got)) Secret (github-pat) detected in session content [turn=2064, source=assistant-tool_use:Bash, line=78]: assert.Equal(t, "configured with the token [REDACTED:github-pat] and still a 401", adder.added[0].content) Secret (github-pat) detected in session content [turn=2064, source=assistant-tool_use:Bash, line=82]: wantURI := "https://tracker.example.com/issue/1?token=[REDACTED:github-pat]" Secret (github-pat) detected in session content [turn=2192, source=assistant-tool_use:Bash, line=13]: wantURI := "https://tracker.example.com/issue/1?token=[REDACTED:github-pat]"''', Secret (github-pat) detected in session content [turn=2192, source=assistant-tool_use:Bash, line=16]: wantURI := "https://tracker.example.com/issue/1?token=[REDACTED:github-pat]" Secret (github-pat) detected in session content [turn=2192, source=assistant-tool_use:Bash, line=17]: assert.Equal(t, "---\nkind: ticket\nuri: "+wantURI+"\n---\nconfigured with the token [REDACTED:github-pat] and still a 401", adder.added[0].content)'''), Secret (github-pat) detected in session content [turn=2192, source=assistant-tool_use:Bash, line=9]: (''' assert.Equal(t, "configured with the token [REDACTED:github-pat] and still a 401", adder.added[0].content) Secret (github-pat) detected in session content [turn=850, source=tool_result, line=234]: + assert.Contains(t, string(got), "configured with the token [REDACTED:github-pat] and still gets a 401") Secret (github-pat) detected in session content [turn=899, source=assistant-tool_use:Bash, line=30]: wantText: "The runner is configured with the token [REDACTED:github-pat] and still gets a 401.", Secret (github-pat) detected in session content [turn=990, source=assistant-tool_use:Write, line=1]: {"content":"//\n// Copyright 2026 The Chainloop Authors.\n//\n// Licensed under the Apache License, Version 2.0 (the "License");\n// you may not use this file except in compliance with the License.... Secret (…) detected in session content [turn=1833, source=assistant-text, line=24]: - Redacting again gives the same result. The scanner is deterministic, and the redactor skips its own [REDACTED:…] placeholders. An unchanged file gives the same bytes and the same digest.
✅ Passed	ai-config-mcp-servers-allowed	ai-coding-session-fd4e67	-

---

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	-

✅ security-context — no advisories

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

View security context ↗ · Security context documentation ↗

⏭️ 3 scans not applied

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

View attestation ↗

---

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 ↗

---

Powered by Chainloop and Chainloop Trace

[cubic-dev-ai]

All reported issues were addressed across 3 files

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

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[migmartri]

thansk

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

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

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>