docs: define participant decision-surface semantics

[Brad-Edwards]

Summary

Define the joint participant-local semantics for tool affordances, decision surfaces, and exposure boundaries so downstream schema, runtime, and conformance work share one authoritative projection model.

Requirement UIDs

• (none — bug/refactor/maintenance run; see Traceability section below)

Related Issues

Closes #119

ADR Impact

• ADR-083

Changes

• Add ADR-083 with seven distinct authority layers, participant/episode/observation-point projection semantics, and cross-stage ownership boundaries.
• Extend the formal participant-semantics specification with SEM-219, SEM-220, and SEM-226 predicates, lifecycle rules, a source-to-contract-to-test matrix, and adversarial counterexamples.
• Record the architecture preflight and update the shared semantic-integrity map to point the requirement cluster at its joint design authority.

Test Plan

• make check passes (Spotless, SpotBugs, Error Prone, Checkstyle, JaCoCo)
• make policy passes (documentation/workflow guardrails)
• Unit tests / integration tests: N/A — docs-only change

Passed ACES_REQUIREMENT_UID=SEM-219 pre-commit run --all-files; the exact repository policy, requirement-governance, and tools/verify_all.py commands; 3,773 unit tests (1 skipped, 46 deselected); 34 integration tests (2 skipped); 92% coverage; and a clean pre-push core/security review.

Ground Control Checks

• make policy passes
• gc_evaluate_quality_gates passes or is unchanged by this repo-only change
• gc_run_sweep reviewed; findings fixed or recorded with rationale

Traceability

• IMPLEMENTS: SEM-219 ← docs/decisions/adrs/adr-083-participant-tool-decision-surface-and-exposure-semantics.md and specs/formal/participant-semantics/README.md, SEM-220 ← docs/decisions/adrs/adr-083-participant-tool-decision-surface-and-exposure-semantics.md and specs/formal/participant-semantics/README.md, SEM-226 ← docs/decisions/adrs/adr-083-participant-tool-decision-surface-and-exposure-semantics.md and specs/formal/participant-semantics/README.md
• TESTS: SEM-219/SEM-220/SEM-226 ← repository policy, participant semantic invariant oracle, Sphinx documentation build, and documentation-only TDD carve-out

Checklist

• Code follows project coding standards (docs/CODING_STANDARDS.md)
• No business logic in API layer
• Domain layer has no framework imports
• Envers @Audited on new entities if applicable
• Changelog fragment: N/A — docs-only change
• Architectural docs updated if stack, package structure, or key behaviors changed

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud