---
paths: "devforgeai/specs/context/**, devforgeai/specs/adrs/**, .claude/rules/**/*.md, **/CLAUDE.md, **/DevForgeAI.md"
---

# Configuration Layer Mutability Rules

**Purpose:** Define which configuration layers can be edited, and how.
**Reference:** ADR-021 (Configuration Layer Alignment Protocol)

---

## Layer Mutability

| Layer | Mutability | Edit Protocol |
|-------|-----------|---------------|
| **CLAUDE.md** | MUTABLE | Direct edit with user approval via AskUserQuestion |
| **System Prompt** | MUTABLE | Direct edit with user approval via AskUserQuestion |
| **Context Files** (6 in `devforgeai/specs/context/`) | IMMUTABLE | Requires ADR approval + `/create-system-architecture` workflow. Never call Edit() directly. |
| **Rules** (`.claude/rules/`) | MUTABLE | Direct edit with user approval via AskUserQuestion |
| **ADRs** (`devforgeai/specs/adrs/`) | APPEND-ONLY | Create a NEW ADR to supersede an existing one (with explicit cross-reference). |
| **AI Companion Manifest** (`devforgeai/workflows/ai-companion-manifest.json`) | MUTABLE (cache) | Generated by `spec-driven-system-architecture` Phase 03 Step 3.2. Committed to git but treated as a derived cache — do not edit by hand. See STORY-631, ADR-053, ADR-070. |
| **test-plan.ai.yaml** (`devforgeai/specs/context/test-plan.ai.yaml`) | IMMUTABLE | Generated by `spec-driven-system-architecture` Phase 03 Step 3.3 (STORY-634). 7th constitutional AI companion artifact. Never edit by hand. See ADR-054, ADR-070. |
| **test-plan-manifest.json** (`devforgeai/workflows/test-plan-manifest.json`) | MUTABLE (cache) | Generated by `spec-driven-system-architecture` Phase 03 Step 3.3. Framework-managed derived cache — do not edit by hand. Dual-parent hash (tech-stack.md + coding-standards.md). See STORY-634, ADR-054, ADR-070. |
| **source-tree/** folder (`devforgeai/specs/context/source-tree/`) | IMMUTABLE | A constitutional context artifact — a *folder* of generated, schema-validated JSON files, not a single file. Regenerated ONLY by `devforgeai-validate generate-source-tree` (under `DEVFORGEAI_ALLOW_CONTEXT_EDIT=1`); never hand-edited. Supersedes `source-tree.md`. See ADR-071, ADR-072. |

---

## Context Files (IMMUTABLE)

The following 6 constitutional context artifacts cannot be modified without an ADR:

1. `devforgeai/specs/context/tech-stack.md`
2. `devforgeai/specs/context/source-tree/` (a generated-JSON *folder* per ADR-071; regenerated only by `devforgeai-validate generate-source-tree`)
3. `devforgeai/specs/context/dependencies.md`
4. `devforgeai/specs/context/coding-standards.md`
5. `devforgeai/specs/context/architecture-constraints.md`
6. `devforgeai/specs/context/anti-patterns.md`

Plus `devforgeai/specs/context/test-plan.ai.yaml` — 7 immutable context artifacts total.

**Enforcement:** `pre-context-file-guard.sh` (PreToolUse[Edit|Write]) blocks Edit/Write to all 7 files with `exit 2`, and (per ADR-071) recursively blocks any file under the `source-tree/` folder. The `/create-system-architecture` context-file generation workflow — and the `generate-source-tree` generator — bypass it per-invocation with `env DEVFORGEAI_ALLOW_CONTEXT_EDIT=1` (scoped only — never `export`).

**ADR append-only enforcement:** `pre-adr-append-only-guard.sh` (PreToolUse[Edit|Write], `exit 2`) blocks Edit/Write to any existing `devforgeai/specs/adrs/ADR-NNN-*.md`. Write to a non-existent ADR file (initial creation) is allowed. Bypass: Pattern A marker `tmp/_adr-status-update.marker` (ADR-081 mechanism — single-shot, <30s fresh, consumed on bypass, audit-logged). See ADR-096.

---

## ADR Propagation Verification

When an ADR is accepted, verify its decisions are propagated to all affected layers:

1. Check CLAUDE.md for references to the ADR's decisions
2. Check rules files for enforcement of the ADR's decisions
3. Check system prompt for alignment with the ADR's decisions
4. Run `/audit-alignment` to detect drift

**Unpropagated ADRs** are detected as "adr_drift" findings by the alignment-auditor subagent.

---

## Contradiction Resolution

When two layers contradict:

1. **IMMUTABLE wins over MUTABLE** — Context files take precedence
2. **Newer ADR wins over older** — Latest accepted ADR is authoritative
3. **Specific wins over general** — Rule file beats CLAUDE.md summary
4. **When ambiguous** — HALT and use AskUserQuestion
