# Membrane Mutation Governance & Integrity Specification

## Overview
This document defines the membrane mutation governance architecture, provenance safeguards, value-restricted spec field constraints, and lifecycle transition enforcement within the ZQK Knowledge Operating System (KOS).

## 1. System Provenance Restriction
System provenance fields are strictly computed and maintained by the storage layer and cannot be manually overridden through ZQL mutations or CLI update commands:
- `created_at`: Set upon object creation.
- `created_by`: Identity of the initial author/account.
- `updated_at`: Automatically refreshed upon every mutation.
- `updated_by`: Identity of the mutating actor.
- `cas_address`: Content-addressable storage locator.
- `hash`: Cryptographic checksum of object contents.

Attempts to manually specify or mutate these fields fail closed unless authorized via an authenticated break-glass context.

## 2. Value-Restricted Spec Fields
Objects admitted through the membrane are validated against their respective schemas:
- **Enums & Categories**: Fields with defined discrete values (such as `category`, `status`, `tier`) reject non-conforming strings.
- **Regex Patterns**: Formatted identifiers and identifiers matching formal naming standards are verified.
- **Numeric Ranges**: Boundary constraints on numeric fields (e.g., effort estimates, metrics) are verified for upper and lower limits.

## 3. Directed Lifecycle Transitions
State transitions across object lifecycles are strictly directed:
- Objects can only transition along edges defined in the lifecycle graph.
- Out-of-order, unearned, or skipped states are rejected at preflight and admission.
- Preconditions (such as criterion validation or test verification) must be satisfied prior to forward promotion.

## 4. Emergency Governance Bypass & Override Friction (`--override`)

In emergency break-glass scenarios where manual state repair or lifecycle precondition bypass is required, the CLI provides strictly audited friction controls via `--override` and `--reason-code`:

### A. Lifecycle Precondition & Gate Bypass (`zqk object update`)
- `--override`: Activates emergency bypass mode, allowing transitions across lifecycle stages even when automated gates (e.g. test verification or criteria validation) are unfulfilled.
- `--reason-code "<justification>"`: Mandatory audited justification explaining why the bypass is necessary.
  - **Friction Gate**: Must be at least 30 characters and at least 5 words.
  - **Non-TTY Block**: Non-interactive shells, background scripts, and autonomous agents are strictly blocked from using `--override`. It must be executed by a human in an authenticated interactive TTY.
  - **Interactive Confirmation**: The operator must type the exact confirmation phrase: `"I acknowledge this bypass introduces process debt"`.
  - **CI Block**: Completely blocked in CI environments (`CI=true`).

### B. Core Object Deletions (`zqk object delete`)
- Hard deletion of core kernel objects is guarded fail-closed and requires `--reason-code "<justification>"` (minimum 30 characters, 5 words).
- Core entities (e.g. `requirement`, `criteria`, `test_case`, `priority_plan`) must be archived (`status: archived`) rather than permanently deleted whenever possible to maintain audit lineage.

### C. Process Debt Minting & Audit Trails
Whenever an `--override` is executed:
1. A durable `process_debt` kernel object is automatically minted recording the bypass reason, target ID, and actor.
2. A structured `audit_event` is appended to `.zqk/streams/` with the security context and timestamp.
3. System check (`zqk system check`) flags active process debt until resolved or validated.