agent-team-foundation · bingran-you · Apr 8, 2026 · Apr 8, 2026
@@ -1,7 +1,7 @@
 ---
 title: "SSH Remote Session and Auth Proxy"
 owners: []
-soft_links: [/integrations/clients/direct-connect-session-bootstrap-and-environment-selection.md, /integrations/clients/remote-session-message-adaptation-and-viewer-state.md, /product-surface/startup-entrypoint-routing-and-session-handoff.md, /platform-services/provider-specific-api-clients-and-auth-routing.md]
+soft_links: [/integrations/clients/direct-connect-session-bootstrap-and-environment-selection.md, /integrations/clients/remote-session-message-adaptation-and-viewer-state.md, /product-surface/startup-entrypoint-routing-and-session-handoff.md, /platform-services/provider-specific-api-clients-and-auth-routing.md, /reconstruction-guardrails/verification-and-native-test-oracles/test-seams-reset-hooks-and-injected-dependencies.md]
 ---
 
 # SSH Remote Session and Auth Proxy

@@ -1,7 +1,7 @@
 ---
 title: "Structured I/O and Headless Session Loop"
 owners: []
-soft_links: [/integrations/clients/sdk-control-protocol.md, /runtime-orchestration/turn-flow/structured-output-enforcement-and-artifact-projection.md, /integrations/clients/sdk-hook-event-transport.md, /runtime-orchestration/turn-flow/unified-command-queue-and-drain.md, /collaboration-and-agents/bridge-contract.md, /platform-services/startup-service-sequencing-and-capability-gates.md, /product-surface/session-state-and-breakpoints.md]
+soft_links: [/integrations/clients/sdk-control-protocol.md, /runtime-orchestration/turn-flow/structured-output-enforcement-and-artifact-projection.md, /integrations/clients/sdk-hook-event-transport.md, /runtime-orchestration/turn-flow/unified-command-queue-and-drain.md, /collaboration-and-agents/bridge-contract.md, /platform-services/startup-service-sequencing-and-capability-gates.md, /product-surface/session-state-and-breakpoints.md, /reconstruction-guardrails/verification-and-native-test-oracles/test-environment-fixtures-and-ci-fail-closed-policy.md]
 ---
 
 # Structured I/O and Headless Session Loop

@@ -13,6 +13,7 @@ Relevant leaves:
 - **[server-contract.md](server-contract.md)** — Umbrella contract from layered MCP server config through admission, connection, live surface exposure, interactive follow-up flows, and recovery.
 - **[config-layering-policy-and-dedup.md](config-layering-policy-and-dedup.md)** — How layered MCP sources, managed policy, project approval, and cross-source dedup produce the live server set.
 - **[oauth-step-up-and-client-registration.md](oauth-step-up-and-client-registration.md)** — How MCP OAuth discovery, callback handling, step-up scope requests, and secure reauth behave.
+- **[federated-auth-conformance-and-idp-test-seeding.md](federated-auth-conformance-and-idp-test-seeding.md)** — How the federated XAA path, SEP-990 expectations, and mock-IdP token seeding behave as a conformance-oriented auth contract.
 - **[connection-and-recovery-contract.md](connection-and-recovery-contract.md)** — Transport types, session recovery, and runtime failure boundaries for MCP servers.
 - **[mcp-surface-state-assembly-and-live-refresh.md](mcp-surface-state-assembly-and-live-refresh.md)** — How connected MCP servers populate and replace session-state tools, commands, skills, and resources, and how `list_changed` refreshes avoid stale slices.
 - **[channel-servers-and-permission-relay.md](channel-servers-and-permission-relay.md)** — Channel admission gates, structured inbound message injection, and optional MCP-mediated permission relay behavior.

@@ -0,0 +1,50 @@
+---
+title: "Federated Auth Conformance and IdP Test Seeding"
+owners: [bingran-you]
+soft_links:
+  - /integrations/mcp/oauth-step-up-and-client-registration.md
+  - /integrations/mcp/server-contract.md
+  - /platform-services/auth-config-and-policy.md
+  - /reconstruction-guardrails/verification-and-native-test-oracles/test-seams-reset-hooks-and-injected-dependencies.md
+---
+
+# Federated Auth Conformance and IdP Test Seeding
+
+The federated MCP auth path has a conformance-sensitive verification contract that is more specific than ordinary OAuth flow coverage. The current snapshot shows a dedicated XAA-style path whose testing posture must preserve both wire-level expectations and deterministic mock-IdP entrypoints.
+
+## Federated auth is not generic OAuth
+
+Equivalent behavior should preserve:
+
+- a distinct federated path instead of silently collapsing back to ordinary per-server consent
+- stable auth-method expectations where conformance relies on a specific token-exchange style
+- persistence of the federated auth server identity and related secure-storage slots across reconnects and refreshes
+
+The main clean-room point is that this path has stricter interoperability expectations than a generic "browser login happened" check.
+
+## Mock-IdP seeding is a supported verification seam
+
+The snapshot shows a direct token-seeding path for cases where the mock identity provider does not serve the full browser authorization surface.
+
+Equivalent behavior should preserve:
+
+- a way to inject a pre-obtained federated identity token for controlled verification contexts
+- storage of that injected token in the same cache slot the ordinary login path later reads
+- expiry handling derived from the token itself when possible, so seeded tokens behave like real cached credentials
+
+This is an important seam because conformance and e2e runs need a deterministic entrypoint that still exercises the real downstream cache and exchange path.
+
+## Wire-level conformance expectations
+
+Equivalent behavior should preserve:
+
+- token-exchange defaults that match the expected conformance posture unless a server explicitly requires another method
+- clear failure when those expectations are violated, instead of silently falling through to a different auth style
+- the distinction between configuration-time secure secrets and login-time seeded tokens
+
+## Failure modes
+
+- **federated fallback surprise**: the runtime silently uses a different auth path than the server contract intended
+- **seed-slot mismatch**: injected test tokens do not land in the same cache identity ordinary auth later reads
+- **wire drift**: token exchange changes method or request shape and quietly stops matching conformance expectations
+- **fake auth success**: tests seed a token into a bypass-only slot and stop exercising the real federated credential path
@@ -1,7 +1,7 @@
 ---
 title: "OAuth, Step-Up, and Client Registration"
 owners: []
-soft_links: [/integrations/mcp/server-contract.md, /integrations/mcp/config-layering-policy-and-dedup.md, /platform-services/auth-config-and-policy.md, /integrations/clients/structured-io-and-headless-session-loop.md]
+soft_links: [/integrations/mcp/server-contract.md, /integrations/mcp/config-layering-policy-and-dedup.md, /platform-services/auth-config-and-policy.md, /integrations/clients/structured-io-and-headless-session-loop.md, /integrations/mcp/federated-auth-conformance-and-idp-test-seeding.md]
 ---
 
 # OAuth, Step-Up, and Client Registration

@@ -24,6 +24,7 @@ Relevant leaves:
 - **[privacy-level-resolution.md](privacy-level-resolution.md)** — Environment-driven privacy postures and how they suppress telemetry or broader optional traffic across the product.
 - **[consumer-privacy-policy-flow.md](consumer-privacy-policy-flow.md)** — Cache-first consumer privacy-policy eligibility, reminder timing, `/privacy-settings`, and headless enforcement behavior.
 - **[settings-change-detection-and-runtime-reload.md](settings-change-detection-and-runtime-reload.md)** — How file-watch and programmatic settings changes are gated, fanned out, and hot-applied across interactive state, headless state, permissions, env, sandbox, and plugin hooks.
+- **[settings-schema-compatibility-and-invalid-field-preservation.md](settings-schema-compatibility-and-invalid-field-preservation.md)** — How settings schema evolution stays backward compatible, how invalid or unknown fields are preserved, and how compatibility tests act as the oracle for safe schema changes.
 - **[usage-analytics-and-migrations.md](usage-analytics-and-migrations.md)** — Telemetry, quotas, updates, and local evolution over time.
 - **[claude-ai-limits-and-extra-usage-state.md](claude-ai-limits-and-extra-usage-state.md)** — The shared Claude.ai quota state machine, warning and recovery surfaces, `/usage`, `/extra-usage`, and the extra-usage couplings that affect fast mode, prompt caching, and 1M model access.
 - **[doctor-command-and-health-diagnostics.md](doctor-command-and-health-diagnostics.md)** — How `/doctor`, `claude doctor`, shared install health checks, and persistent diagnostics aggregate warnings across settings, sandboxing, plugins, MCP, and context.

@@ -1,7 +1,7 @@
 ---
 title: "Auth, Config, and Policy"
 owners: []
-soft_links: [/integrations/mcp/server-contract.md, /collaboration-and-agents/remote-and-bridge-flows.md]
+soft_links: [/integrations/mcp/server-contract.md, /collaboration-and-agents/remote-and-bridge-flows.md, /platform-services/settings-schema-compatibility-and-invalid-field-preservation.md]
 ---
 
 # Auth, Config, and Policy

@@ -1,7 +1,7 @@
 ---
 title: "Mock Rate Limit Scenarios and Test Contracts"
 owners: [bingran-you]
-soft_links: [/platform-services/claude-ai-limits-and-extra-usage-state.md]
+soft_links: [/platform-services/claude-ai-limits-and-extra-usage-state.md, /reconstruction-guardrails/verification-and-native-test-oracles/native-test-derived-asset-provenance-and-acceptance-rules.md]
 native_source: services/mockRateLimits.ts
 verification_status: native_test_derived
 ---

@@ -1,7 +1,7 @@
 ---
 title: "Settings Change Detection and Runtime Reload"
 owners: []
-soft_links: [/platform-services/policy-and-managed-settings-lifecycle.md, /platform-services/sync-and-managed-state.md, /tools-and-permissions/permissions/permission-rule-loading-and-persistence.md, /tools-and-permissions/permissions/sandbox-selection-and-bypass-guards.md, /integrations/plugins/plugin-runtime-contract.md, /ui-and-experience/shell-and-input/keybinding-customization-and-context-resolution.md]
+soft_links: [/platform-services/policy-and-managed-settings-lifecycle.md, /platform-services/sync-and-managed-state.md, /tools-and-permissions/permissions/permission-rule-loading-and-persistence.md, /tools-and-permissions/permissions/sandbox-selection-and-bypass-guards.md, /integrations/plugins/plugin-runtime-contract.md, /ui-and-experience/shell-and-input/keybinding-customization-and-context-resolution.md, /platform-services/settings-schema-compatibility-and-invalid-field-preservation.md]
 ---
 
 # Settings Change Detection and Runtime Reload

@@ -0,0 +1,53 @@
+---
+title: "Settings Schema Compatibility and Invalid-Field Preservation"
+owners: [bingran-you]
+soft_links:
+  - /platform-services/auth-config-and-policy.md
+  - /platform-services/settings-change-detection-and-runtime-reload.md
+  - /platform-services/doctor-command-and-health-diagnostics.md
+  - /reconstruction-guardrails/verification-and-native-test-oracles/test-framework-overview.md
+---
+
+# Settings Schema Compatibility and Invalid-Field Preservation
+
+Settings evolution in Claude Code is guarded as a stable product contract, not as an incidental implementation detail. The visible snapshot treats backward compatibility tests as the oracle for safe schema changes and preserves invalid or unknown content rather than rewriting user files into a narrower shape.
+
+## Compatibility contract
+
+Equivalent behavior should preserve:
+
+- additive evolution as the default posture for public settings
+- a dedicated compatibility lane guarding settings-file changes
+- rejection of breaking schema changes as a product-level regression, not only as a typing concern
+
+The important design point is that settings compatibility is not left to convention alone. It is explicitly treated as something tests must defend.
+
+## Invalid and unknown field preservation
+
+Equivalent behavior should preserve:
+
+- unknown or invalid settings surviving on disk even when they are not currently usable
+- selective filtering of bad sub-rules where the system can safely preserve the rest of the file
+- type coercion or passthrough behavior where that protects durable compatibility instead of silently narrowing the accepted shape
+- user-facing repair surfaces being able to report problems without having already destroyed the offending data
+
+This means the system prefers "ignore and report" over "drop and rewrite" for many invalid settings scenarios.
+
+## Why this belongs in platform services
+
+This is not just a test note. It shapes:
+
+- configuration loading behavior
+- validation reporting
+- hot reload semantics
+- migration safety
+- doctor and diagnostics surfaces
+
+The test lane is the oracle, but the contract itself is a platform behavior.
+
+## Failure modes
+
+- **breaking-tightening regression**: a schema change makes existing user files invalid without an intentional migration path
+- **destructive cleanup**: invalid or unknown fields are removed from disk and users lose the information needed to repair them
+- **all-or-nothing rejection**: one malformed rule causes the whole settings file to become unusable when narrower preservation was possible
+- **testless drift**: schema evolution continues without compatibility tests defending the user-facing contract
@@ -1,7 +1,7 @@
 ---
 title: "Startup Service Sequencing and Capability Gates"
 owners: []
-soft_links: [/platform-services/interactive-startup-and-project-activation.md, /platform-services/policy-and-managed-settings-lifecycle.md, /platform-services/trust-and-capability-hydration.md, /platform-services/bootstrap-and-service-failures.md, /platform-services/user-settings-sync-contract.md, /platform-services/usage-analytics-and-migrations.md, /integrations/clients/structured-io-and-headless-session-loop.md]
+soft_links: [/platform-services/interactive-startup-and-project-activation.md, /platform-services/policy-and-managed-settings-lifecycle.md, /platform-services/trust-and-capability-hydration.md, /platform-services/bootstrap-and-service-failures.md, /platform-services/user-settings-sync-contract.md, /platform-services/usage-analytics-and-migrations.md, /integrations/clients/structured-io-and-headless-session-loop.md, /reconstruction-guardrails/verification-and-native-test-oracles/test-environment-fixtures-and-ci-fail-closed-policy.md]
 ---
 
 # Startup Service Sequencing and Capability Gates

@@ -1,7 +1,7 @@
 ---
 title: "Usage, Analytics, and Migrations"
 owners: []
-soft_links: [/platform-services/startup-service-sequencing-and-capability-gates.md, /platform-services/bootstrap-and-service-failures.md, /platform-services/claude-ai-limits-and-extra-usage-state.md, /product-surface/interaction-modes.md, /runtime-orchestration/state/build-profiles.md]
+soft_links: [/platform-services/startup-service-sequencing-and-capability-gates.md, /platform-services/bootstrap-and-service-failures.md, /platform-services/claude-ai-limits-and-extra-usage-state.md, /product-surface/interaction-modes.md, /runtime-orchestration/state/build-profiles.md, /reconstruction-guardrails/verification-and-native-test-oracles/test-environment-fixtures-and-ci-fail-closed-policy.md]
 ---
 
 # Usage, Analytics, and Migrations
@@ -59,6 +59,7 @@ Equivalent behavior should preserve:
 - heavier telemetry initialization waiting until trust-gated environment/config effects are ready
 - some telemetry paths deferring further until remote managed settings have loaded, so org-controlled env/config overlays affect telemetry posture before it starts
 - privacy or essential-traffic posture being able to suppress outbound analytics work without suppressing the whole product
+- test posture being able to suppress telemetry and adjacent feedback-style side effects entirely, so automated runs do not emit nonessential traffic or pick up timing noise from support systems
 - telemetry or diagnostics failure remaining non-fatal to the interactive session
 
 ## Local migrations evolve persisted behavior

@@ -15,3 +15,4 @@ Use these leaves before adding any new knowledge:
 - **[knowledge-lifecycle.md](knowledge-lifecycle.md)** — How extracted knowledge moves from observation to durable tree state, and how bad knowledge is detected.
 - **[rebuild-phasing.md](rebuild-phasing.md)** — Implementation order for a clean-room rebuild, including what must ship together.
 - **[tree-expansion-strategy.md](tree-expansion-strategy.md)** — How this repository should deepen from high-level coverage into reconstruction-ready subsystem contracts over repeated passes.
+- **[verification-and-native-test-oracles/](verification-and-native-test-oracles/NODE.md)** — How cross-domain test framework knowledge, fixture oracles, and native-test-derived contract assets should be normalized without becoming a source mirror.
@@ -0,0 +1,22 @@
+---
+title: "Verification and Native Test Oracles"
+owners: [bingran-you]
+soft_links:
+  - /reconstruction-guardrails/source-boundary.md
+  - /reconstruction-guardrails/knowledge-lifecycle.md
+  - /platform-services/NODE.md
+  - /tools-and-permissions/NODE.md
+  - /integrations/NODE.md
+---
+
+# Verification and Native Test Oracles
+
+This subdomain captures cross-cutting knowledge about how the observed Claude Code build verifies itself. It exists because the tree already has domain-owned test contracts, but it still lacked one place to describe the shared verification architecture that spans runtime posture, fixtures, seams, and evidence quality.
+
+Relevant leaves:
+
+- **[test-framework-overview.md](test-framework-overview.md)** — The layered shape of the current test system, including the visible tier model and the boundary between confirmed and inferred runner details.
+- **[test-environment-fixtures-and-ci-fail-closed-policy.md](test-environment-fixtures-and-ci-fail-closed-policy.md)** — How test posture suppresses side effects, how fixture replay works, and why missing recordings fail closed in CI.
+- **[test-seams-reset-hooks-and-injected-dependencies.md](test-seams-reset-hooks-and-injected-dependencies.md)** — The narrow seams the product uses to keep hard behaviors testable without turning the whole runtime into a debug harness.
+- **[native-test-derived-asset-provenance-and-acceptance-rules.md](native-test-derived-asset-provenance-and-acceptance-rules.md)** — How native test knowledge should be normalized into clean-room contract assets and how those assets should be linked back to their owning domains.
+- **[evidence-levels-and-missing-artifacts.md](evidence-levels-and-missing-artifacts.md)** — What this source snapshot proves, what it only strongly suggests, and which missing artifacts still block exact runner-level reproduction.