Document durable admission assessments and risk-aware shadow policy

[ezutfen]

This PR adds comprehensive documentation for two major admission-control features and updates deployment/configuration guidance across multiple docs.

Summary

Adds design documentation, deployment configuration, and API reference updates for:

1. Durable admission assessments (issue ENG-PROMOTION-003D — Persist promotion assessments and expose next-action state #159) — append-only recording of every Path A promotion/admission decision with canonical decision hashing, outcome/next-action vocabularies, and operator-facing APIs for inspection and legacy backfill
2. Risk-aware shadow admission policy (issue ENG-PROMOTION-003C — Replace the universal 72-hour gate with versioned risk-based admission profiles #158) — declarative, pure-function policy evaluation against three recall surfaces using effective risk/epistemic/retention assessments, shadow-only (no authority over actual promotions)

Key Changes

• docs/design.md: Added two new sections (§9a and §9b) documenting both features with full contract references, outcome/next-action vocabularies, operator surface (endpoints, CLI commands), and implementation status notes
• docs/deployment.md:
  • Added §7b "Recall tuning" with comprehensive tables for recall budgets, freshness, anti-feedback-loop penalties, and relationship-aware expansion configuration
  • Clarified ENGRAM_PROVISIONER_DATABASE_ROLE configuration requirement
  • Fixed documentation of ENGRAM_HOST/ENGRAM_PORT (currently dead code, always bind 0.0.0.0:8000)
  • Updated portal enrollment gating documentation
• .env.example: Added configuration sections for admission assessments capture flag, relationship-aware recall expansion weights/limits, anti-feedback-loop penalty tuning, and clarified dead host/port settings
• adapters/mcp-server/README.md:
  • Added engram_assessments and engram_reassess tool documentation
  • Updated engram_diary_write to document admin representation via on_behalf_of_principal_id and deprecate legacy principal parameter
  • Clarified visibility parameter now includes public option
• docs/embeddings.md: Added engram setup-embeddings validation command documentation and clarified activation coverage threshold configuration
• docs/service-provisioning.md: Clarified delegation.review.issue permission for purpose-bound review brokers
• adapters/engram-hooks/README.md: Added ENGRAM_HOOKS_REPORT_LIFECYCLE_TELEMETRY configuration option
• docs/usage-metering.md: Updated provider call event types to include extraction
• README.md: Added high-level summaries of both admission features with links to full ADR documentation

Implementation Status

Both features are documented as:

• ENG-PROMOTION-003D — Persist promotion assessments and expose next-action state #159 (Durable assessments): Implemented behind disabled ENGRAM_ADMISSION_ASSESSMENT_CAPTURE_ENABLED flag; production behavior unchanged when disabled
• ENG-PROMOTION-003C — Replace the universal 72-hour gate with versioned risk-based admission profiles #158 (Risk-aware shadow): Implemented as shadow-only; path_a_compat remains sole authoritative profile

All documentation includes explicit notes that these are observability/audit features that do not change promotion thresholds, weights, or lane rules.

https://claude.ai/code/session_01EEb5QpuqsPoTo6ZPjqn6Ah