spec: 003 Spec capture during the session

[migmartri]

This PR adds spec 003. The spec changes the session spec capture of spec 002. It does not replace spec 002.

Summary

Today the agent captures the spec only at session start. It also captures the user prompt, which the transcript already holds. With this change:

• The agent does not capture the user's request prompt. A spec that the user pastes is still captured.
• A short reminder at each user turn tells the agent to capture a spec in four cases only: the user pastes or gives a new spec, the user pastes or gives an image, the user approves a plan (captured as kind text), or a spec changes. A design note that the session writes outside the repository is a spec that changes.
• The limit of spec files for each session goes from 10 to 25.

The Decision Record keeps two behaviors as they are today. A spec added after the last push is recorded with the next AI-assisted commit. A push after the session ends holds no spec.

Open questions for reviewers

None. The Decision Record holds the answers from drafting.

Refs #3515

AI disclosure: Claude Code helped write this spec.

🤖 Posted by Maximus bot (Claude Code) on behalf of @migmartri

[chainloop-platform]

AI Session Checks — 🟢 88% · ✅ 0 failing

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 88%	2	✅ 0	98% AI / 2% Human	1	+137 / -14	34m23s

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

Oct 5, 2026 10:04 UTC · 26m25s · $4.06 · 144 in / 52.6k out · claude-code 2.1.289 (claude-opus-5-5)

View session details ↗

Change Summary

• Adds docs/specs/003-spec-capture-during-session.md for spec capture during a session.
• Refines the capture rules to skip request prompts, preserve changed specs, and keep approved plans.
• Documents the per-turn reminder flow, agent-specific channels, and the raised 25-file capture limit.

AI Session Overall Score

🟢 90% — Spec-only PR with strong setup and clean execution; implementation verification remains for later code work.

AI Session Analysis Breakdown

🟢 92% · alignment

🟢 The final PR summary matches the session's signed spec-only commit. · High Impact

🟢 91% · scope-discipline

No notes.

🟢 90% · context-and-planning

🟢 The user supplied a full spec-writing skill before drafting began. · High Impact

🟢 88% · user-trust-signal

🟢 The follow-up about approved plans was collaborative, not corrective. · Medium Impact

abstained · solution-quality

No notes.

abstained · verification

🟡 Verification and solution quality were not assessed because this PR only changes a design spec. · Low Severity

Missing criteria: solution-quality, verification

---

File Attribution

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

Status	Attribution	File	Lines
modified	ai	docs/specs/003-spec-capture-during-session.md	+130 / -8

---

Policies (4)

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

🟢 87% — 84% AI — ✅ All policies passing

Oct 5, 2026 11:44 UTC · 7m58s · $1.59 · 60 in / 14.1k out · claude-code 2.1.289 (claude-opus-5-5)

View session details ↗

Change Summary

• Updates docs/specs/003-spec-capture-during-session.md for PR review feedback.
• Clarifies pasted-image handling by pointing back to Spec 002 behavior.
• Revises the file-limit rule so earlier recorded specs are never dropped after overwrites.

AI Session Overall Score

🟢 87% — Spec-only review-fix session stayed focused; runtime validation was out of scope.

AI Session Analysis Breakdown

🟢 96% · scope-discipline

🟢 All edits stayed in the single spec file under review. · High Impact

🟢 92% · alignment

🟢 AI summarized the pasted-image fix and later edits matched that summary. · High Impact

🟢 83% · user-trust-signal

No notes.

🟡 72% · context-and-planning

🟢 AI fetched review comments and code context before editing. · High Impact

🟠 Opening context was only the branch name, so the AI had to reconstruct task scope. · Medium Severity

💡 When the ask is just a branch or PR handle, restate goals and constraints before editing.

abstained · solution-quality

🟡 Solution quality abstained because the session updated design text rather than executable behavior. · Low Severity

abstained · verification

🟡 Verification abstained because the session only changed spec text, not runtime behavior. · Low Severity

---

File Attribution

████████████████░░░░ 84% AI / 16% Human

Status	Attribution	File	Lines
modified	ai	docs/specs/003-spec-capture-during-session.md	+7 / -6

---

Policies (4)

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

---

Security Checks — ✅ 5 passing

✅ secret-scan

Status	Policy	Messages
✅ Passed	secrets-detection	-

✅ sast-scan

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

✅ 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 1 file

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

Re-trigger cubic</sub>

[jiparis]

sounds good, thanks!