docs(attestation): publish A2A required-fields contract (lr-a850d0)

[clagentic-builder]

What

Publishes the A2A caller-attestation required-fields contract as a standalone, normative doc (docs/A2A-ATTESTATION-CONTRACT.md) and gives it a mechanically-checkable Go-level source of truth (internal/attestation/contract.go's RequiredIdentityContractFields), plus end-to-end regression tests tying DomainResolver and the structured sidecar parser together for both the conforming-record and missing-required-field cases.

Why

lr-a850d0's AC 1-6 call for: (1) one deterministic documented sidecar source for an A2A caller, (2) fail-closed MISS with no parent-session fallback, (3) structured record fields (identity + parent session id) available to the mint path, (4) a published required-fields contract a crew-manifest producer can implement with zero gatekeeper-source knowledge, (5) a missing required field refusing with a structured, field-naming error, and (6) same-PR doc updates.

The substrate for AC 1/2/3/5 already landed on main via PR #23 (lr-f1bfe8's structured identity_field + lr-2ca216's domain-aware fail-closed DomainResolver) -- both dependency blockers this task listed are closed (task comment #2/#3). What was still missing was the AC#4/#6 deliverable: a standalone, normative required-fields contract doc (the task explicitly lists it separately from the SETUP/design chapter and the config example, which already existed), a mechanically-checkable field-name reference a producer or its own tests can import instead of re-typing the four attribution field names, and a regression test proving the missing-field refusal specifically through the DomainA2A path (existing coverage exercised the sidecar provider directly, not chained through DomainResolver).

This task is the CONSUMER-side attestation contract only -- no token minting/issuance is implemented here (downstream lr-890fae), and no A2A mint command is wired into cmd/gatekeeper. Branch-neutral per the substrate-ratification decision (lr-7f9969, Option B): this contract is identical regardless of whether gatekeeper or OpenBao ultimately issues the token.

Changes

• docs/A2A-ATTESTATION-CONTRACT.md (new): the normative required-fields contract -- deterministic sidecar-source rule, required-fields table, missing-field refusal semantics, pointer to the Go contract list.
• internal/attestation/contract.go (new): RequiredIdentityContractFields, a canonical slice of the four OPTIONAL attribution field names, mirroring structured_sidecar.go's existing constants.
• internal/attestation/contract_test.go (new): pins the published field list to its Go source, plus two end-to-end regression tests -- conforming-record-through-DomainA2A (AC#4) and missing-required-field-refused-through-DomainA2A (AC#5).
• docs/SETUP.md: the existing A2A section now points at the standalone doc instead of duplicating its table.
• docs/SIDECAR-READ-CONTRACT.md, docs/DESIGN.md, config.example.yaml: cross-references to the new doc.

Test status

go build ./..., go vet ./..., and go test ./... -count=1 all pass (7 packages, all ok). No existing test was modified.

Task: lr-a850d0

[clagentic-security]

BOBBIE security audit of PR #24 (lr-a850d0, A2A caller-attestation required-fields contract).

Scope: base d1378d5..head 3820d05 (7 files: config.example.yaml comment update, docs/A2A-ATTESTATION-CONTRACT.md new, docs/DESIGN.md, docs/SETUP.md, docs/SIDECAR-READ-CONTRACT.md, internal/attestation/contract.go new, internal/attestation/contract_test.go new).

Findings: none.

Checks performed:

• config.example.yaml diff is a comment-only cross-reference update (points to the new doc); no new fields, no real credentials, placeholder env names (MY_HARNESS_SPAWN_ID), /tmp dir — consistent with pre-existing pattern.
• internal/attestation/contract.go adds only an exported []string of the four OPTIONAL attribution field names (parent_session_id, spawn_id, agent_type, spawned_at); the REQUIRED identity field name is never hardcoded, matching the contract doc statement that it is deployment-config-named only.
• No change to internal/attestation/domain_policy.go, structured_sidecar.go, sidecar.go, or chain.go in this diff (verified via git diff on those paths) - fail-closed MISS semantics and the PerSpawn-required refusal for DomainA2A are untouched by this PR.
• No trust-boundary regression: the new test file only adds regression coverage for the existing fail-closed refusal (MalformedSidecarError, not ErrNoIdentity/ErrPerSpawnRequired) and a conforming-record resolve path; no assertions loosen prior behavior.
• No dependency manifest (go.mod/go.sum) touched; no new imports outside stdlib in contract.go.
• gitleaks: no leaks found. semgrep --config=auto on the two new Go files: 0 findings. trufflehog binary unavailable in this environment (recorded in scanner_status). osv-scanner: no lockfile diff in scope, not applicable.

review.status: clean

{"reviewer": "bobbie", "review_status": "clean", "head_sha": "3820d0547aa18b92abf20786ae47f4fa7ae2aef7", "pr_number": 24}

[clagentic-reviewer]

PEACHES - clean (0 findings)

Reviewed against amos.code-craft (1-13) + amos.path-choice (2-5).

All five critical verifications pass:

• contract.go RequiredIdentityContractFields references the structured_sidecar.go constants (not re-hardcoded)
• TestDomainResolver_A2A_ConformingRecord_AllContractFieldsAvailable chains through real DomainResolver, asserts all 5 contract fields
• TestDomainResolver_A2A_MissingRequiredField_RefusedWithStructuredError chains through real DomainResolver with session sidecar present, asserts MalformedSidecarError.Field set (not ErrNoIdentity, not ErrPerSpawnRequired)
• No hardcoded crew/agent proper names in product code
• Docs normative and de-duplicated: A2A-ATTESTATION-CONTRACT.md standalone, SETUP.md table removed and redirects to it, all cross-links resolve

No blockers.

{"reviewer": "peaches", "review_status": "clean", "head_sha": "3820d0547aa18b92abf20786ae47f4fa7ae2aef7", "pr_number": 24}

[clagentic-merger]

Merged via clagentic-loadout v0.1.0

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