---
paths: ".claude/plans/**/*.md"
---

# Plan File Archive Policy

**Purpose:** Prevent provenance-chain breakage by mandating archival (not deletion) of plan files that are referenced by epics, brainstorms, stories, ADRs, or any other framework artifact.

**Scope:** All files under `.claude/plans/*.md`.

**Reference:** STORY-573 audit findings F-003 (broken plan_file ref) + F-001 archive policy approval session 2026-05-11; canonical full reference at `.claude/memory/plan-file-archive-policy.md`.

---

## The Rule

Plan files referenced in any provenance-chain artifact MUST be archived to `.claude/plans/archive/`, NOT deleted.

A plan file is "in the provenance chain" if it is named in any of:

| Artifact | Field / Pattern |
|----------|----------------|
| Epic frontmatter | `plan_file:` |
| Brainstorm frontmatter or body | `Feeds Into: <path>` field |
| Story frontmatter | `plan_file:` (if extended schema adopts it) |
| ADR | Plan citations in `## Context` or `## Decision` sections |
| Any other artifact | Reference to a `.claude/plans/*.md` path |

Deletion permanently breaks the provenance chain — `/validate-stories --chain` Sub-Phase 3a will emit `provenance/broken_plan_ref` MEDIUM findings that cannot be cleanly remediated (the plan content is irretrievable).

---

## Enforcement

The `pre-plan-file-rm-guard.sh` PreToolUse[Bash] hook enforces this: it blocks (exit 2) any `rm`/`git rm` of a `.claude/plans/*.md` file (not under `archive/`) that is still referenced in a provenance-chain artifact, and emits the archive instructions. Unreferenced plans and already-archived plans are deletable. To delete a referenced plan anyway, run the `rm` from a non-sandboxed terminal (the hook does not fire there) — but the referencer must then be updated separately or `/validate-stories --chain` will emit irrecoverable `provenance/broken_plan_ref` findings.

---

## Archive Procedure (canonical)

```bash
# Step 1: Create archive directory if it doesn't exist (one-time)
mkdir -p .claude/plans/archive/

# Step 2: Move the plan file
mv .claude/plans/<plan-file>.md .claude/plans/archive/<plan-file>.md

# Step 3: Find all referencers
grep -rln ".claude/plans/<plan-file>.md" devforgeai/specs/ .claude/

# Step 4: Update each referencer to point at the archived path
# (Manual or scripted — choose based on referencer count)
sed -i 's#.claude/plans/<plan-file>.md#.claude/plans/archive/<plan-file>.md#g' <each_referencer>

# Step 5: Add a Change Log entry to each updated epic/story/ADR documenting the archival
```

**Sandbox note:** Steps 2 + 4 + 5 may require a non-sandboxed terminal if any of the referencers live under protected operational paths. The sandbox typically allows writes under `.claude/plans/` itself but blocks operational mirrors. See `.claude/rules/workflow/operational-safety.md` Rule 4.

---

## Detection (post-hoc)

The `/validate-stories <scope> --chain` command's Sub-Phase 3a (`validate_provenance_chain` in `src/claude/skills/spec-driven-stories/references/custody-chain-workflow.md`) already detects this defect class. Two finding subtypes are emitted, both MEDIUM:

| Finding type | Trigger | Recoverable? |
|--------------|---------|--------------|
| `provenance/stale_referencer_path` | Plan file at `.claude/plans/archive/` but referencer not updated | YES — update the referencer |
| `provenance/broken_plan_ref` | Plan file genuinely absent (deleted, not archived) | NO — content lost; best fix is "deleted" breadcrumb |

The `find_file_with_archive_fallback()` helper in Sub-Phase 3a currently supports `devforgeai/specs/` subtrees but NOT `.claude/plans/`. Extending the helper to support `.claude/plans/` is a tracked framework improvement (see `.claude/memory/plan-file-archive-policy.md` § "Implementation note").

---

## Pre-Deletion Verification (Recommended Practice)

Before deleting any file under `.claude/plans/`, run:

```bash
plan_name="<plan-file>.md"
echo "Provenance-chain referencers for ${plan_name}:"
grep -rln "${plan_name}" devforgeai/specs/Epics/ devforgeai/specs/brainstorms/ devforgeai/specs/Stories/ devforgeai/specs/adrs/ 2>/dev/null
```

- If output is empty: the plan is unreferenced. Deletion is safe.
- If output is non-empty: archive instead (see Archive Procedure above).

---

## References

- **Canonical full reference:** `.claude/memory/plan-file-archive-policy.md` (project-side memory, auto-loaded)
- **Triggering audit:** `devforgeai/qa/audit/custody-chain-audit-STORY-573.md` Rev 7 (2026-05-11) finding F-003
- **Detection logic:** `src/claude/skills/spec-driven-stories/references/custody-chain-workflow.md` Sub-Phase 3a
- **Parallel archival convention (stories):** `devforgeai/specs/Stories/archive/long-term/` semantics governed by ADR-064 (`Archive Long-Term Cross-State Dependencies`)
- **Sandbox protection:** `.claude/rules/workflow/operational-safety.md` Rule 4
- **Cross-references:** `.claude/rules/conditional/plan-file-creation.md` § "Plan Retirement" and DevForgeAI.md § "Plan File Convention" (Enforcement note) both cite this rule

---

**Version:** 1.0 | **Created:** 2026-05-11 | **Source:** STORY-573 F-003 remediation session
