Improve AI and contribution documentation governance

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,11 +2,72 @@
 
 Describe the change and its motivation.
 
-## Checklist
+## Change Area (required)
+
+- [ ] API-only managed change (`WebRtcNet.Api` / managed-only behavior)
+- [ ] Interop / marshaling / native-boundary change
+- [ ] Docs/infra only (no behavior change)
+
+## Required Evidence (for behavioral/API changes)
+
+If this change affects WebRTC or Media Capture behavior, complete all sections below.  
+If not applicable, write `N/A - no behavioral change`.
+
+### 1) W3C reference (required when applicable)
+
+- Spec section link(s):
+- Relevant requirement quote(s):
+
+### 2) Google source reference (required when applicable)
+
+Provide pinned references: path + revision context (commit SHA or branch/tag).
+
+- Source path(s):
+- Revision context (SHA/branch/tag):
+- Notes on alignment:
+
+### 3) Intended observable behavior (required when applicable)
+
+Describe externally observable behavior (state transitions, event ordering, timing, errors).
+
+- Behavior summary:
+- Why this behavior is correct:
+
+### 4) Divergence from Google reference (required if diverging)
+
+- [ ] No divergence
+- [ ] Divergence exists (explain below)
+- Divergence details (what differs, why .NET/runtime needs require it, and which web-observable semantics are preserved):
+
+## Test Evidence (required)
+
+### Tests added/updated
+
+- 
+
+### Commands run + results
+
+- 
+
+### Change-area test gate confirmation
+
+- [ ] API-only managed change: ran managed NUnit tests
+- [ ] Interop/native-boundary change: ran interop unit tests (when environment available)
+- [ ] Required environment unavailable (explain below)
+
+### If environment unavailable (required when checked above)
+
+- Missing environment/dependency:
+- What was run instead:
+- Residual risk:
+
+## Documentation
 
-- [ ] I ran relevant build/tests for changed code.
 - [ ] I updated documentation for externally visible behavior changes.
-- [ ] If this PR changes W3C-aligned API behavior (`WebRtcNet.Api`), I reviewed:
-	- `documents\crosswalk\webrtcnet-api-to-spec.md`
-	- `documents\specs\index\spec-map.md`
-	- Local spec snapshots (refreshed via `.\scripts\update-spec-docs.ps1` when needed)
+- [ ] No external docs impact.
+
+## Spec/Crosswalk Review (required for W3C-aligned behavior changes)
+
+- [ ] Reviewed `documents\crosswalk\webrtcnet-api-to-spec.md`
+- [ ] Reviewed `documents\specs\index\spec-map.md`
+- [ ] Refreshed/checked local spec snapshots (`.\scripts\update-spec-docs.ps1`) when needed

Agents.md

@@ -0,0 +1,112 @@
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked, but do surface these orphans to me.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## 5. Standards and Source Alignment (AI-Specific)
+
+### 5.0 Instruction precedence and scope
+
+- If guidance conflicts, apply this order:
+	1. higher-level runtime/system constraints
+	2. this `Agents.md`
+	3. path- or tool-specific guidance
+	4. ad hoc workflow suggestions
+- `Agents.md` defines AI execution behavior and guardrails.
+- Human contributor workflow requirements live in `CONTRIBUTING.md`.
+
+### 5.1 Authority and implementation order
+
+- **MUST** treat W3C specs as normative intent for behavior and semantics.
+- **MUST** treat Google implementations as the primary implementation reference.
+- **MUST** use this lookup order when implementing behavior:
+	1. `libwebrtc` API/implementation
+	2. Blink bindings/behavior glue
+	3. Chromium tests and call sites
+- **MAY** adapt for .NET/runtime constraints, but adaptations **MUST** be minimal and **MUST NOT** change required observable behavior unless explicitly documented.
+
+### 5.2 Web-compatibility obligations
+
+- Changes **MUST** preserve web-expected behavior across:
+	- state machine transitions
+	- promise/task resolution timing
+	- event ordering
+	- error taxonomy
+- If exact parity is not feasible, the deviation **MUST** be explicit and justified.
+
+### 5.3 .NET API mapping rules
+
+- Public .NET APIs **MUST** use standard .NET naming/casing.
+- XML docs **MUST** map terms back to relevant W3C concepts when names differ.
+- Promise-style APIs **MUST** map to `Task`/`ValueTask`.
+- Event callbacks **MUST** map to .NET events with `EventArgs`.
+- `CancellationToken` **SHOULD** be used where cancellation/timeout semantics apply.
+- Legacy callback-style `navigator.getUserMedia(...)` support is **OUT OF SCOPE**.
+
+### 5.4 Media Capture scope for this project
+
+- Media Capture scope and priority policy are defined in `CONTRIBUTING.md`.
+
+### 5.5 Divergence, failures, and traceability
+
+- When diverging from Google reference behavior, changes **MUST** include:
+	- upstream Google reference (path + revision context)
+	- what differs
+	- why .NET/runtime needs require it
+	- which web-observable semantics are preserved
+	- test evidence for preserved behavior
+- Implementations **MUST NOT** use silent no-ops or success-shaped stubs for unsupported features.
+- Unsupported features **MUST** fail explicitly.
+- Keep concise source intent hints in code/XML docs; keep fuller rationale in PR/issue documentation.

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to WebRtcNet
+
+This document defines contributor workflow requirements for this repository.
+
+## 1. Behavioral alignment requirements
+
+When a change affects WebRTC or Media Capture behavior, contributors **MUST**:
+
+1. Reference the relevant W3C requirement(s).
+2. Reference upstream Google implementation behavior.
+3. Demonstrate expected observable behavior in tests.
+
+Upstream references **MUST** be pinned to a revision in PR/issue notes (path + commit/branch context) so behavior can be re-validated later.
+
+## 2. Required PR evidence block
+
+PR descriptions for behavioral changes **MUST** include:
+
+1. **W3C reference**: section link(s)
+2. **Google source reference**: libwebrtc/Blink/Chromium path(s) and revision context
+3. **Behavior summary**: what observable behavior is intended and why
+4. **Test evidence**: tests added/updated and what they prove
+
+For `WebRtcNet.Api` behavior changes, PRs **MUST** also update or validate:
+
+- `documents\specs\index\spec-map.json` (canonical API symbol to spec anchor map)
+- `documents\specs\index\spec-map.md` (human-readable mirror)
+- `documents\crosswalk\webrtcnet-api-to-spec.md` (implementation status/adaptation notes)
+
+## 3. Test gates by change area
+
+- API-only managed changes **MUST** run managed NUnit tests.
+- Interop/marshaling/native-boundary changes **MUST** also run interop unit tests when environment support is available.
+- If a required environment is unavailable, PRs **MUST** explicitly call that out and identify what was run instead.
+
+## 4. Scope priorities for Media Capture
+
+- Prioritize WebRTC-critical Media Capture functionality first.
+- `P0`: `getUserMedia`, track lifecycle/events, and constraints needed for call setup quality.
+- `P1`: device enumeration/change and high-value constraints/settings (including `backgroundBlur`).
+- Legacy callback `navigator.getUserMedia(success, error)` is out of scope.
+- Extended constraints beyond immediate needs are in near-term scope and should be added incrementally.

README.md

@@ -6,6 +6,11 @@ WebRtcNet currently uses WebRTC branch-heads/7778, which corresponds to Chromium
 
 See [WebRTC 1.0: Real-time Communication Between Browsers](https://www.w3.org/TR/webrtc/) for API documentation.
 
+## Contribution and AI guidance
+
+- Human contributor workflow requirements: `CONTRIBUTING.md`
+- AI execution guardrails for this repository: `Agents.md`
+
 ## Local W3C spec corpus
 
 This repository keeps a local standards corpus in `documents\specs\` to support standards-alignment work in `WebRtcNet.Api` without repeated web fetching.

docs/adr/README.md

@@ -0,0 +1,28 @@
+# Architecture Decision Records (ADRs)
+
+This folder stores architectural decisions that affect implementation direction, constraints, and tradeoffs.
+
+## ADR index
+
+| ADR | Title | Status |
+| --- | --- | --- |
+| [0001](0001-host-entry-point-for-api-access.md) | Host entry point for API access | accepted |
+| [0002](0002-caller-callee-tcp-alignment.md) | Caller/Callee TCP alignment | accepted |
+
+## ADR format (required)
+
+Each new ADR should include these sections:
+
+1. Status
+2. Date
+3. Context
+4. Decision
+5. Consequences
+6. Alternatives considered
+7. References (issues/PRs/spec sections/code paths)
+
+## Guidance
+
+- Keep ADRs concise and decision-focused.
+- Link affected code paths and related tests when possible.
+- Supersede prior ADRs explicitly rather than silently changing direction.

documents/crosswalk/webrtcnet-api-to-spec.md

@@ -4,6 +4,11 @@ Status: seeded
 
 This crosswalk maps high-value `WebRtcNet.Api` symbols to current W3C specification anchors and records expected adaptation notes for .NET usage.
 
+Source-of-truth note:
+
+- `documents\specs\index\spec-map.json` is the canonical API symbol to spec anchor map.
+- This crosswalk adds implementation status, adaptation notes, and priority guidance.
+
 ## WebRTC 1.0
 
 | API Symbol | Spec Section | Anchor URL | Status | Adaptation Notes |

documents/specs/index/README.md

@@ -2,8 +2,23 @@
 
 This folder contains cross-spec metadata.
 
-Planned files:
+Canonical files:
 
 - `spec-map.json`: Machine-readable map from API symbols to spec anchors.
-- `spec-map.md`: Human-readable map.
+- `spec-map.md`: Human-readable map (derived from `spec-map.json`).
 - `update-log.md`: Refresh history and source metadata.
+
+## Source-of-truth policy
+
+- `spec-map.json` is the source of truth for API symbol to W3C anchor mapping.
+- `spec-map.md` should be kept in sync with `spec-map.json`.
+- `documents\crosswalk\webrtcnet-api-to-spec.md` captures implementation status and adaptation notes.
+
+## Status vocabulary
+
+Use one of the following values for mapping and implementation status:
+
+- `seeded`
+- `partial`
+- `implemented`
+- `todo`