docs(attestation): add canonical sidecar read-contract spec (lr-61cc4a)

[clagentic-builder]

What

Adds docs/SIDECAR-READ-CONTRACT.md: the canonical, generalized spec for the read side of the identity-sidecar convention. Links it from docs/DESIGN.md (attestation module description) and docs/SETUP.md (existing attestation.sidecars config section).

Why

Reader sprawl finding (lr-1cd33c seq-3): four independent sidecar-read implementations of varying fidelity exist across the fleet (Gatekeeper Go dual-adapter is the correct reference; others degenerate in various ways). The write side is already solid and untouched by this change. This doc fixes the read contract once, in generalized shapes, so any reader can be brought into line without adopting Gatekeeper specific naming.

The spec states, generically, no tool names normative:

1. Two sidecar classes - spawn-scoped keyed by a spawn-id env var, session-scoped keyed by a session-id env var.
2. Resolution order: spawn-first then session; first hit wins.
3. No hit = fail closed for identity-bearing decisions - never an OS-user fallback for a named caller.
4. Atomic symlink-safe read: no-follow open plus fstat regular-file check before reading.
5. Symlink or non-regular file at the expected path = hard failure, not a soft miss.
6. Directory, prefix, and env-var-name values always come from the consumer own config, never hardcoded in code.
7. The session sidecar lore-agent-name- prefix is LORE-owned and stays as is - no rename proposed.

Gatekeeper own deployed attestation.sidecars config block (config.example.yaml) and its reference implementation (internal/attestation/sidecar.go, internal/attestation/chain.go) are cited as a worked example, explicitly marked illustrative, not normative naming.

Convention is netrc-style: each consumer repo (loadout, gatekeeper, lore) carries or links this spec and implements it against its own config, with zero runtime coupling. The loadout and lore linking sections are separate already-filed tasks (lr-8e1593 comment seq-2; lr-1ac929) and are out of scope for this PR per the dispatch (holden, lr-61cc4a comment 3).

Task

lr-61cc4a

Test status

Doc-only change. go build ./... and go test ./... both pass; no functional code touched.

[clagentic-reviewer]

PEACHES — clean (1 nit)

• docs/SIDECAR-READ-CONTRACT.md:195 — peaches.nit.observation — Worked example config shows session entry before spawn entry; section 2 recommends spawn-first. While spec (line 204) correctly acknowledges this as a config ordering to reconcile locally, the example could guide readers better by showing spawn first (matching section 2) even if current deployment differs.

{"reviewer": "peaches", "review_status": "clean", "head_sha": "f97abd1fcb9cab2c46363f9ee43c9190b1a33376", "pr_number": 21}

[clagentic-security]

BOBBIE security audit for PR #21 (lr-61cc4a). Doc-only change: new docs/SIDECAR-READ-CONTRACT.md, plus cross-link additions in docs/DESIGN.md and docs/SETUP.md. No source, config, or workflow code touched.

Reviewed the new spec content and the worked-example config block for secret/credential exposure, sensitive-path disclosure, and injectable content. The YAML excerpt (dir: /tmp, file_prefix: lore-agent-name-/crew-agent-spawn-, session_id_env: CLAUDE_CODE_SESSION_ID/CREW_SPAWN_AGENT_ID) matches the already-committed config.example.yaml values verbatim -- placeholder/example naming, not a new disclosure. No live credentials, tokens, or host-specific paths found. No executable/copy-paste shell content in the new doc.

gitleaks: 0 leaks on the PR commit. semgrep (auto config): 0 findings across the changed markdown files. osv-scanner: not applicable, no dependency manifests changed.

Zero findings. review.status: clean.

{"reviewer": "bobbie", "review_status": "clean", "head_sha": "9367684f5f3b1d3210472d9ab381365dd9e8ba4c", "pr_number": 21}

[clagentic-reviewer]

PEACHES — clean (prior nit resolved)

Prior finding (comment 5016847082 @ f97abd1): worked-example config in docs/SIDECAR-READ-CONTRACT.md listed session-scoped before spawn-scoped, contradicting section 2's spawn-first normative recommendation.

Resolution: Commit 9367684 reordered the worked example to lead with spawn-scoped (lines 171–182), followed by session-scoped (lines 183–189). Section 2's normative "spawn-first, then session" ordering is now consistent with the example. Lines 200–206 add an honest callout: Gatekeeper's currently deployed config.example.yaml lists session-first as a config-local choice; the doc clarifies that this is a reconciliation task separate from the contract itself, and the worked example leads with spawn-first to illustrate the spec's own recommendation.

No findings against amos.code-craft (minimal change, no hardcoded secrets/hosts/paths) or amos.path-choice (not applicable to documentation). Additions to docs/DESIGN.md and docs/SETUP.md correctly link to the canonical spec; both are clear and properly scoped.

{"reviewer": "peaches", "review_status": "clean", "head_sha": "9367684f5f3b1d3210472d9ab381365dd9e8ba4c", "pr_number": 21}

[clagentic-merger]

Merged via clagentic-loadout v0.1.0

Field	Value
Gated HEAD SHA	9367684f5f3b1d3210472d9ab381365dd9e8ba4c
Merged SHA	9367684f5f3b1d3210472d9ab381365dd9e8ba4c
Reviews	clagentic-reviewer[bot], clagentic-security[bot]
CI status	no-runner-by-design (0 commit-status entries at HEAD)
task_id	lr-61cc4a