REQ-FUN-096

Global read-only mode controlled by AIPM_READ_ONLY environment variable

ID: REQ-FUN-096
Category: Functional Requirements
Status: approved
Priority: P0
Created: 2026-05-10T18:38:03.937Z
Approved: 2026-05-10T18:38:54.930Z
Updated: 2026-05-10T18:38:54.930Z

What

System SHALL support a global read-only mode controlled by the AIPM_READ_ONLY environment variable; mode applies to api/web/mcp processes uniformly.

Why

Inspired by AoE; needed for baseline-freeze review windows, change-control gates, incident response. See arch_decision_readonly_mode memory.

How

FastAPI middleware ahead of route handlers returns 403 with code=read_only_mode on POST/PATCH/PUT/DELETE; documented allowlist (audit-verify, logout, health, session refresh) preserved. AIPM_READ_ONLY_REASON, AIPM_READ_ONLY_DETAILS_URL, AIPM_READ_ONLY_SEVERITY companion vars surface context. X-AIPM-Read-Only response header drives web UI banner.

Done when

When AIPM_READ_ONLY=1, all unsafe HTTP methods (except allowlist) return 403 with structured envelope; web UI shows persistent banner; mode activation/deactivation logged in audit_log; restart required to flip.

Out of scope

In-band toggle (deliberately not exposed via API).

established project management guidelines Mapping

Primary Knowledge Area: Integration Management
Secondary KA: Risk Management
Primary Process Group: Monitoring & Controlling
established project management guidelines Deliverable: Change Management Plan

Global read-only mode is an operational safety switch - controlled change to executing-work admission.