spec: 004 Pi coding agent support in Chainloop Trace

[waveywaves]

This PR adds Spec 004 only. It changes no implementation code. The implementation issue is #3520.

Summary

The spec designs native Chainloop Trace support for the Pi coding agent.

• trace init --pi and trace run --pi install one marked, project-local Pi extension without overwriting an unrelated file.
• Pi lifecycle and built-in write, edit, and bash events use the existing Trace hook pipeline without blocking Pi.
• An optional normalized tool_call_id prevents concurrent Pi calls from overwriting each other's snapshots while preserving existing-provider behavior.
• The provider copies and parses persisted Pi JSONL v3, rejects stale refreshes, persists /tree selection with a plain custom marker, and emits the existing AI coding-session evidence schema.
• Pi receives the full model instruction once per session and the short Spec 003 capture reminder on every user turn.
• Start banners and post-push links use Pi UI where available; headless links use stderr without corrupting stdout.
• The design pins Pi 0.80.10 as the compatibility baseline and defines trust, timeout, output-bound, shutdown-reason, corruption, --no-session, and fork behavior.
• Existing provider defaults, control-plane APIs, protobufs, and attestation schemas stay unchanged.

Decisions for reviewers

Please challenge these choices in particular:

• D-001/D-002: generate a marked .pi/extensions/chainloop-trace.ts instead of requiring a Pi fork or separate package.
• D-007: append a plain custom marker after session_tree, then parse from the last persisted entry.
• D-011: do not make pre-push discover sessions whose Pi hooks never ran.
• D-012: add optional tool_call_id only to normalized local hook/snapshot state.
• D-013: bound each hook subprocess to five seconds and 64 KiB per output stream.
• D-015: deliver post-push links through Pi UI or headless stderr.

Verification

• Rebased on current main; the filename and title use the next available number, Spec 004.
• Checked every requirement against the current Trace provider, hook, state, pre-push, and evidence paths.
• Checked lifecycle, session-tree, custom-message, trust, mode, and tool-event claims against Pi 0.80.10 docs and installed types/runtime.
• Reconciled Pi behavior with accepted Spec 003's per-turn capture reminder.
• git diff --check

Refs #3520

AI assistance

pi helped research and write this spec. The commit carries an Assisted-by: pi trailer.

[chainloop-platform]

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	-

✅ 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 — ⚠️ 1 failing

Status	Policy	Material	Messages
⚠️ Failed	pr-min-approvals	pr-info	PR/MR #3523 has 0 approving reviews, 1 required.
✅ Passed	pr-description-required	pr-info	-
✅ Passed	pr-user-story-linked	pr-info	-

View attestation ↗

---

Powered by Chainloop and Chainloop Trace

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}