spec: 001 Project and Organization from .chainloop.yml in Attestations

[migmartri]

Summary

This PR adds a design spec. It adds no code. The spec proposes that the attestation commands read projectName and organization from .chainloop.yml. These are the keys that chainloop trace init already writes. Today the attestation commands read only projectVersion from the file. With this change, a repository owner can pin the project and the organization for all attestations from the repository. Flags and environment variables continue to take precedence over the file.

The spec also defines one way to find and read the file for the attestation and trace commands. It also fixes a gap: attestation init skips some flag checks when the file is missing.

This PR also initializes docs/specs/ and adds a short section about specs to CLAUDE.md.

The spec takes a different approach from PR #3065. It keeps the key name projectName from trace, and it keeps the project required (decisions D-001 and D-003).

Questions for reviewers

The spec has no open questions. Please challenge the decisions in the Decision Record, mainly these:

• D-002: the file takes precedence over the organization that the CLI saved as the default.
• D-004: all attestation commands read the organization from the file, not only init.

Refs #3063

AI disclosure: Claude Code helped to write this spec.

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

[chainloop-platform]

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

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 90%	1	⚠️ 1	100% AI / 0% Human	3	+149 / -9	23m22s

🟢 90% — 100% AI — ⚠️ 1 policies failing

Sep 29, 2026 21:54 UTC · 23m22s · $6.46 · 228 in / 77.0k out · claude-code 2.1.285 (claude-opus-5-5)

View session details ↗

Change Summary

• Adds docs/specs/001-attestation-repo-config.md for attestation init to read projectName and organization from .chainloop.yml.
• Initializes docs/specs/README.md and repo guidance in CLAUDE.md for future spec work.
• Revises the spec to define --org precedence and API-token organization mismatch handling.

AI Session Overall Score

🟢 90% — Well-framed spec session stayed aligned and tightly scoped; runtime checks were not applicable.

AI Session Analysis Breakdown

🟢 93% · scope-discipline

🟢 The recorded commits stayed on the spec and its expected init files. · High Impact

🟢 91% · alignment

🟢 The AI folded the later --org requirement into the same spec. · High Impact

🟢 88% · context-and-planning

🟢 Detailed eng-spec instructions grounded the drafting before edits began. · High Impact

🟢 86% · user-trust-signal

No notes.

abstained · solution-quality

🟡 Solution quality was not assessed because the PR is spec-only and ships no implementation. · Low Severity

abstained · verification

🟡 Verification was not assessed because the PR changes docs and guidance, not runtime behavior. · Low Severity

---

File Attribution

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

Status	Attribution	File	Lines
modified	ai	docs/specs/001-attestation-repo-config.md	+144 / -9
modified	ai	CLAUDE.md	+4 / -0
created	ai	docs/specs/README.md	+1 / -0

---

Policies (4, 1 failing)

Status	Policy	Material	Messages
✅ Passed	ai-config-no-dangerous-commands	ai-coding-session-d332cc	-
✅ Passed	ai-config-ai-agents-allowed	ai-coding-session-d332cc	-
⚠️ Failed	ai-config-no-secrets	ai-coding-session-d332cc	Secret (generic-password) detected in session content [turn=347, source=tool_result, line=6]: INF redacted secrets from the AI coding session before upload count=10 rules=["generic-[REDACTED:generic-password]"]
✅ Passed	ai-config-mcp-servers-allowed	ai-coding-session-d332cc	-

---

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>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>