fix: enforce explicit permission-mode precedence (V8) and land 2026-06-12 governance batch

Permission-mode precedence (V8, P0):
- Explicit --permission-mode is never overridden by workspace config:
  demotion (config read-only over explicit prompt) and escalation
  (config allow over explicit prompt) both blocked, repro-verified
- Shared _UNSET sentinel across all 11 parser sites (9 converted to
  sentinel; 2 intentional read-only defaults kept); sentinel-aware merges
  in apply_config_defaults and apply_workspace_defaults_to_namespace;
  _finalize_permission_mode() in main() prevents sentinel leaks
- Precedence now: explicit CLI > workspace config > built-in default
- Bidirectional integration tests in tests/integration/test_config_loader.py

Governance hardening:
- Agent contribution contract (V4-a/c/d): docs/agent-contribution-contract.md
  plus CI gate via scripts/check_agent_contribution_contract.py; no
  self-service bypass (bypass attempts are critical errors), fixture-tested
- ADR 0031: shadow-mode exit criteria with expiry 2026-09-12 (V3-a)
- Fix half-finished rename in runner/_core.py that raised NameError on the
  destructive-tool approval path (failed:system instead of pending_approval)
- Correct acceptance count to pytest-collected truth: 646 (was 648/643 drift)
- Roadmap/compliance/ADR-index doc updates; regenerated docs inventory

Review record:
- docs/analysis/intent-verification-delta-2026-06-12.md records the six-pass
  verification delta (intent re-derivation, ledger verification, findings
  V1-V9, work list)

Constraint: explicit CLI permission mode must always win over workspace config; config still applies when the flag is not given; no behavior change for non-permission config keys
Tested: acceptance tier 646/646, smoke 200/200, first-hour e2e + config-loader + governance-compliance 68 passed, docs validator 0 errors, ruff check+format clean, mypy clean (1004 files), escalation/demotion repro both blocked
Not-tested: full unit suite (historically resource-limited here; smoke+acceptance tiers used per WDG-002), CI execution of the new contract gate on GitHub
Confidence: high

Agent: Claude Code (parallel-agent contributions reviewed and integrated)
Agent-Session: six-pass reflective review, 2026-06-12
Roadmap-Status: updated
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: johnteee

.github/workflows/ci.yml

@@ -216,6 +216,12 @@ jobs:
           echo "Comparing test assertions against base: $BASE"
           python3 scripts/check_test_assertion_regression.py --base "$BASE"
 
+      - name: Agent contribution contract gate (V4-a)
+        # Validates agent-authored commits comply with contribution contract.
+        # NO SELF-SERVICE BYPASS: Agents cannot bypass their own governance gate (V4-c fix).
+        # Manual bypass requires human intervention via GitHub UI only.
+        run: python3 scripts/check_agent_contribution_contract.py --commit HEAD
+
   governance-gate:
     runs-on: ubuntu-latest
     # Run after lint passes, before package build

docs/acceptance.md

@@ -42,7 +42,7 @@ acceptance flow writes the user TUI state file. In sandboxed environments, run
 them with permission to bind localhost ports and write the TeaAgent state
 directory.
 
-**Current acceptance test count: `648 passed`** (pytest-collected guard target; suite summary at `docs/generated/suite-summary.json`, 2026-06-12)
+**Current acceptance test count: `646 passed`** (pytest-collected guard target)
 
 Keep historical acceptance-count snapshots in dated analysis or roadmap docs.
 This file only owns the live guard target.

docs/adr/0031-shadow-mode-exit-criteria.md

@@ -0,0 +1,75 @@
+# ADR 0031: Shadow Mode Exit Criteria
+
+## Status
+
+Proposed — 2026-06-12
+
+**Expiry review:** 2026-09-12 (re-score whether policy/RBAC shadow mode should promote to enforce)
+
+## Context
+
+Sprint 2 wired policy engine and RBAC in shadow mode (log, don't enforce) as documented in:
+- `teaagent/governance/h4_integration.py` (policy shadow code)
+- `teaagent/runner/_approval_manager.py` (RBAC shadow code)
+- Roadmap H4 rows cite WDA-002/003
+
+Shadow mode allows production observation without enforcement risk, but lacks clear exit criteria. Without defined evidence requirements and an expiry date, "wired" quietly becomes the new "implemented but unwired" — the exact failure mode WDA-006 was designed to prevent.
+
+## Decision
+
+**Define** the evidence required to promote policy/RBAC from shadow to enforce mode, with an expiry date for shadow status.
+
+### Exit Criteria
+
+Policy/RBAC may be promoted from shadow to enforce mode only when **all** of the following evidence is satisfied:
+
+1. **Audit trail validation**: Shadow-mode logs show zero false positives over a 30-day production window
+   - Evidence: Automated analysis of audit logs showing no blocked actions that should have been allowed
+   - Test: `tests/acceptance/test_policy_as_code_flow.py` with enforce-mode fixture passes
+
+2. **Coverage completeness**: All policy rules have corresponding acceptance tests
+   - Evidence: Claim-to-test traceability matrix shows 100% coverage for policy/RBAC claims
+   - Test: `tests/acceptance/test_claim_traceability.py` passes for policy/RBAC section
+
+3. **Performance impact**: Enforcement overhead stays within SLO
+   - Evidence: Benchmark shows <50ms median latency for policy checks
+   - Test: Performance regression gate passes with policy enforcement enabled
+
+4. **Human review**: Security and governance owners sign off on promotion
+   - Evidence: ADR acceptance with owner signatures
+   - Process: PR review with explicit "Approve shadow→enforce promotion" sign-off
+
+5. **Rollback plan**: Documented rollback path to shadow mode if issues arise
+   - Evidence: Runbook entry for disabling enforcement without data loss
+   - Test: Rollback procedure validated in staging environment
+
+### Expiry
+
+Shadow status for policy/RBAC enforcement **expires on 2026-09-12**. On expiry:
+
+- If exit criteria are met: Promote to enforce mode via this ADR acceptance
+- If exit criteria are not met: Either (a) extend shadow status with new ADR citing blocking evidence, or (b) revert shadow wiring and document gaps
+
+### Implementation Steps for Promotion
+
+When exit criteria are satisfied and expiry date is reached:
+
+1. Update `teaagent/governance/h4_integration.py` to remove `shadow_mode=True` flag
+2. Update `teaagent/runner/_approval_manager.py` to enable RBAC enforcement
+3. Add acceptance test for enforce-mode behavior
+4. Update roadmap H4 rows to mark policy/RBAC as "enforce" status
+5. Accept this ADR with expiry date achieved
+
+## Consequences
+
+- Positive: Clear, evidence-based promotion path prevents "permanent shadow" anti-pattern
+- Positive: Expiry date forces explicit decision-making (promote, extend, or revert)
+- Negative: Requires additional validation work before enforcement can ship
+- Negative: May delay enforcement if exit criteria are difficult to satisfy
+
+## References
+
+- [Work Direction Decomposition (WDA-002/003)](../plans/work-direction-decomposition-2026-06-10.md)
+- [Intent Verification Delta (V3)](../analysis/intent-verification-delta-2026-06-12.md)
+- ADR 0029 (consensus validation deferral precedent)
+- `docs/architecture/control-loop-ownership-map-2026-06-11.md`

docs/adr/README.md

@@ -32,6 +32,7 @@ This directory contains all Architecture Decision Records (ADRs) for the TeaAgen
 | 0024 | Automated Memory Invalidation | Accepted and Implemented | 2026-05-29 | - |
 | 0025 | Shared ChatSessionController for Chat Surfaces | Accepted and Implemented | 2026-06-01 | 2026-06-04 13:18:00 +0800 |
 | 0029 | Consensus Validation Deferred Behind Approval Queue | Accepted | 2026-06-10 | 2026-12-10 (expiry review) |
+| 0031 | Shadow Mode Exit Criteria | Proposed | 2026-06-12 | 2026-09-12 (expiry review) |
 
 ## ADR Categories
 
@@ -47,11 +48,13 @@ This directory contains all Architecture Decision Records (ADRs) for the TeaAgen
 - **0007**: ANP Adapter Boundary - External federation boundary
 - **0008**: P4 Strategic Posture - Storage, TLS, P2P auth posture
 
-### Governance Hardening (0009, 0022-0024)
+### Governance Hardening (0009, 0022-0024, 0029, 0031)
 - **0009**: 5-Loop Governance System - Comprehensive governance loops
 - **0022**: Centralized Approval Queue for Subagents - Batch approval management
 - **0023**: Strict Plan-Before-Write Enforcement - Plan validation
 - **0024**: Automated Memory Invalidation - Memory hygiene
+- **0029**: Consensus Validation Deferred Behind Approval Queue - Consensus gate deferral
+- **0031**: Shadow Mode Exit Criteria - Policy/RBAC shadow→enforce promotion path
 
 ### Multi-Agent & Swarm (0019)
 - **0019**: Phase 4 - Federated Swarm Consensus & Peer Attestations - Swarm coordination

docs/agent-contribution-contract.md

@@ -0,0 +1,126 @@
+# Agent Contribution Contract
+
+> **Purpose:** Define the required gates and validation steps that any AI agent (Claude Code, Devin, subagent, or other harness) must pass before contributing to the TeaAgent repository.
+>
+> **Scope:** All automated commits to the TeaAgent repository, regardless of which agent harness authored them.
+>
+> **Status:** Active (V4-a, 2026-06-12)
+
+## Problem Statement
+
+The TeaAgent repository is now edited by multiple agent harnesses (Claude Code sessions, subagent lanes, Devin, plus the human owner). TeaAgent's product is agent governance, but its own contribution path had no agent-facing contract. This led to V1 (drift gate failure on main) where a false "verified" claim landed via a second AI agent.
+
+## Required Pre-Commit Gates
+
+Before any agent-authored commit can be made, the following validations must pass:
+
+### 1. Docs Consistency Gate
+
+**Command:** `python3 scripts/validate_docs_consistency.py --test-quality-mode off`
+
+**Purpose:** Ensures documentation claims match runtime state and prevents drift.
+
+**What it checks:**
+- Acceptance test count in `docs/acceptance.md` matches pytest collection
+- Provider counts are consistent across README, architecture.md, and runtime
+- Docs inventory is up to date
+- Suite summary freshness (WDB-004) if test counts are cited
+- Roadmap required fields are present
+- Risk register and ticket index evidence coverage
+
+**Failure mode:** Gate exits non-zero; commit must not proceed.
+
+### 2. Test Collection Gate
+
+**Command:** `python3 -m pytest tests/acceptance --collect-only -q`
+
+**Purpose:** Ensures the test suite is collectible (no import errors, missing dependencies).
+
+**Failure mode:** Collection fails with import errors (e.g., missing `hypothesis` in system Python).
+
+**Note:** The repo venv (`.venv/bin/python`) is preferred for consistency with docs gate.
+
+### 3. Lint and Format Gate
+
+**Commands:**
+```bash
+ruff check .
+ruff format --check .
+```
+
+**Purpose:** Ensures code style consistency and catches common errors.
+
+**Failure mode:** Non-zero exit from either command.
+
+### 4. Type Check Gate
+
+**Command:** `mypy teaagent/ tests/ --explicit-package-bases`
+
+**Purpose:** Ensures type annotations are correct and complete.
+
+**Failure mode:** Non-zero exit from mypy.
+
+## Claim-Bearing Files Requiring Passing Gates
+
+The following files contain governance-relevant claims and require a passing gate in the same commit that modifies them:
+
+| File | Claim Type | Required Gate |
+|------|------------|---------------|
+| `docs/acceptance.md` | Acceptance test count | `test_docs_acceptance_count_accuracy.py` must pass |
+| `README.md` | Provider count, feature claims | Provider consistency validation must pass |
+| `docs/architecture.md` | Architecture claims, provider counts | Provider consistency validation must pass |
+| `docs/roadmap-status.md` | Roadmap claims, status values | Roadmap validation must pass |
+| `docs/governance-compliance.md` | Governance gate mappings | Docs consistency validation must pass |
+| `docs/generated/suite-summary.json` | Test suite results | Must be regenerated with current commit |
+
+## Commit Trailer Requirements
+
+Agent-authored commits should include the following trailers for traceability:
+
+```
+Agent: <agent-name> (e.g., "Claude Code", "Devin", "subagent")
+Agent-Session: <session-id-or-context>
+Reviewed-by: <human-optional>
+```
+
+Example:
+```
+fix: update acceptance test count to 646
+
+Agent: Devin
+Agent-Session: cli-2026-06-12-001
+```
+
+## CI Enforcement
+
+The `use-case-matrix` job in `.github/workflows/ci.yml` runs the docs consistency gate as a required check. Branch protection rules must require this check to pass before merging to main.
+
+## Emergency Override
+
+**NO SELF-SERVICE BYPASS ALLOWED** (V4-c fix): Agents cannot bypass their own governance gate via trailers or environment variables. This prevents the exact failure mode the contract is designed to prevent.
+
+In rare cases where a gate must be bypassed (e.g., fixing the gate itself):
+1. Human must temporarily disable the CI check via GitHub UI
+2. Commit with trailer: `Manual-bypass: <reason> <ticket-id>`
+3. Open a PR referencing the bypass
+4. Human review required before merge
+5. Re-enable CI check after merge
+
+## Implementation Status
+
+- ✅ Docs consistency gate exists and runs in CI
+- ✅ Test collection gate exists as acceptance count accuracy test
+- ✅ Lint/format/type check gates exist in CI
+- ✅ Agent contribution contract gate exists in CI (V4-a)
+- ✅ Anti-bypass enforcement implemented (V4-c) - no self-service bypass allowed
+- ✅ Fixture tests for contract gate (V4-d) - `tests/test_governance_compliance.py::TestAgentContributionContract`
+- ✅ Python interpreter preference (venv over system) for consistency (third-pass fix)
+- ✅ Auto-regenerate docs inventory to avoid staleness from multi-agent concurrent edits (third-pass fix)
+- ⚠️ Branch protection enforcement requires manual GitHub configuration (see V1-b)
+
+## References
+
+- V1 finding: Drift gate failed open on commit `e2e8317`
+- V4 finding: Multi-agent contribution surface ungoverned
+- `docs/governance-compliance.md` for full gate mapping
+- `scripts/validate_docs_consistency.py` for gate implementation