spec: 004 Role, title, and description of each spec source by jiparis · Pull Request #3532 · chainloop-dev/chainloop

jiparis · 2026-10-06T11:19:15Z

Design spec for review. This PR adds only the spec. It adds no code.

Summary

This spec changes the spec capture of Spec 002 and Spec 003. It does not replace them. Today each spec source has a kind: ticket, document, image, or text. The kind tells the format of a source, but not its purpose. With this change, the agent can also record a role for each source: task, spec, plan, or reference. The CLI stores the role in the session material and in the annotations of the spec material. A tool that shows the sources can then group them by purpose.

For reviewers

The spec has no open questions. These decisions are the most likely to get challenges:

D-003: a binary file gets its role from a companion file that the agent writes, named <file>.meta.yaml. The CLI does not guess a role for an image.
D-004: a missing or unknown role gives no role in the evidence. The CLI does not derive a role from the kind.

Refs #3531

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev>

chainloop-platform · 2026-10-06T11:19:24Z

AI Session Checks — 🟢 84% · ✅ 0 failing

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 84%	1	✅ 0	100% AI / 0% Human	1	+222 / -59	21h21m33s

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

Oct 5, 2026 15:05 UTC · 21h21m33s · $56.42 · 1.3k in / 598.4k out · claude-code 2.1.289 (claude-opus-5-5)

View session details ↗

Change Summary

Updates platform spec 003 for the AI session Context tab: source grouping, title-based labels, transcript placement, and a Skills group.
Updates OSS spec 004 to add optional role, title, and description metadata plus redaction rules for spec sources.
Refreshes related review-thread decisions and design artifacts so both specs stay aligned.

AI Session Overall Score

🟢 84% — Well-planned spec work; only the early OSS workaround merits reviewer attention.

AI Session Analysis Breakdown

🟢 94% · context-and-planning

🟢 The eng-spec prompt and research gave the work clear upfront structure. · High Impact

🟢 93% · scope-discipline

No notes.

🟢 91% · user-trust-signal

🟢 The user kept delegating follow-up work, showing steady confidence overall. · High Impact

🟢 90% · alignment

No notes.

🟡 68% · solution-quality

🟢 AI corrected the trace gap with Edit-based, signed, attested commits. · High Impact

🟠 AI first opened the OSS PR from a scratch clone/API path, so the initial PR missed trace attribution. · Medium Severity

💡 When a workflow constraint blocks normal commits, ask before using an untracked workaround.

abstained · verification

🟡 Verification abstained: reviewed commits are spec/design changes, so no runtime behavior was validated. · Low Severity

Missing criteria: verification

File Attribution

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

Status	Attribution	File	Lines
modified	ai	`docs/specs/003-ai-session-spec-viewer.md`	+222 / -59

Policies (4)

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

Security Checks — ✅ 5 passing

✅ `secret-scan`

Status	Policy	Messages
✅ Passed	`secrets-detection`	-

✅ `sast-scan`

Status	Policy	Messages
✅ Passed	`cwe-top25`	-
✅ Passed	`owasp-top10-2025`	-
✅ Passed	`sast`	-
✅ 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-description-required`	`pr-info`	-
✅ Passed	`pr-user-story-linked`	`pr-info`	-
✅ Passed	`pr-min-approvals`	`pr-info`	-

View attestation ↗

Powered by Chainloop and Chainloop Trace

cubic-dev-ai

No issues found across 1 file

_{Re-trigger cubic}

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev> Chainloop-Trace-Sessions: d4043d7b-f121-41dd-a642-42aff4c66211

cubic-dev-ai

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

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

Re-trigger cubic}

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev> Chainloop-Trace-Sessions: d4043d7b-f121-41dd-a642-42aff4c66211

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.

Re-trigger cubic}

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev> Chainloop-Trace-Sessions: d4043d7b-f121-41dd-a642-42aff4c66211

spec: 004 Role of each spec source

1ffb3b0

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev>

jiparis added the spec Design spec label Oct 6, 2026

jiparis requested a review from migmartri October 6, 2026 11:19

jiparis marked this pull request as ready for review October 6, 2026 11:37

cubic-dev-ai Bot reviewed Oct 6, 2026

View reviewed changes

spec: 004 add an optional title to each spec source

04c25ab

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev> Chainloop-Trace-Sessions: d4043d7b-f121-41dd-a642-42aff4c66211

jiparis changed the title ~~spec: 004 Role of each spec source~~ spec: 004 Role and title of each spec source Oct 6, 2026

cubic-dev-ai Bot reviewed Oct 6, 2026

View reviewed changes

Comment thread docs/specs/004-spec-source-role.md Outdated

spec: 004 redact every title before it goes into the evidence

c2d92a6

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev> Chainloop-Trace-Sessions: d4043d7b-f121-41dd-a642-42aff4c66211

migmartri previously approved these changes Oct 6, 2026

View reviewed changes

Comment thread docs/specs/004-spec-source-role.md Outdated

spec: 004 add an optional description to each spec source

cf2bf68

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev> Chainloop-Trace-Sessions: d4043d7b-f121-41dd-a642-42aff4c66211

jiparis dismissed migmartri’s stale review via cf2bf68 October 6, 2026 12:20

jiparis changed the title ~~spec: 004 Role and title of each spec source~~ spec: 004 Role, title, and description of each spec source Oct 6, 2026

cubic-dev-ai Bot reviewed Oct 6, 2026

View reviewed changes

Comment thread docs/specs/004-spec-source-role.md

spec: 004 show the description in the binary file example

77fc1ce

Refs chainloop-dev#3531 Signed-off-by: Jose I. Paris <jiparis@chainloop.dev> Chainloop-Trace-Sessions: d4043d7b-f121-41dd-a642-42aff4c66211

jiparis requested a review from migmartri October 6, 2026 12:25

migmartri approved these changes Oct 6, 2026

View reviewed changes

jiparis merged commit a2dc7a4 into chainloop-dev:main Oct 6, 2026
17 checks passed

jiparis deleted the issue-3531-spec-role branch October 6, 2026 13:00

jiparis mentioned this pull request Oct 6, 2026

spec: 005 Pi coding agent support in Chainloop Trace #3523

Merged

Navigation Menu

Repository navigation

spec: 004 Role, title, and description of each spec source - #3532

spec: 004 Role, title, and description of each spec source#3532
jiparis merged 5 commits into
chainloop-dev:mainfrom
jiparis:issue-3531-spec-role

jiparis commented Oct 6, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

chainloop-platform Bot commented Oct 6, 2026 •

edited

Loading

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

Change Summary

AI Session Overall Score

AI Session Analysis Breakdown

🟢 94% · context-and-planning

🟢 93% · scope-discipline

🟢 91% · user-trust-signal

🟢 90% · alignment

🟡 68% · solution-quality

abstained · verification

File Attribution

Policies (4)

⏭️ 3 scans not applied

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Summary

For reviewers

Uh oh!

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

Uh oh!

AI Session Checks — 🟢 84% · ✅ 0 failing

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

Change Summary

AI Session Overall Score

AI Session Analysis Breakdown

🟢 94% · context-and-planning

🟢 93% · scope-discipline

🟢 91% · user-trust-signal

🟢 90% · alignment

🟡 68% · solution-quality

abstained · verification

File Attribution

Policies (4)

Security Checks — ✅ 5 passing

✅ secret-scan

✅ sast-scan

✅ security-context — no advisories

⏭️ 3 scans not applied

PR validation — ✅ 3 passing

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jiparis commented Oct 6, 2026 •

edited by cubic-dev-ai Bot

Loading

chainloop-platform Bot commented Oct 6, 2026 •

edited

Loading

✅ `secret-scan`

✅ `sast-scan`

✅ `security-context` — no advisories

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading