# P1.5 Documentation Consolidation Plan

**Date:** 2025-12-22  
**Status:** 🎯 Ready for Implementation  
**Baseline:** `v1.0.11-p0-p1.4-complete`

---

## Objective

Create a **single authoritative documentation index** that clearly separates:
- **Policy (contracts)** vs **Narrative (guides)**
- **Active** vs **Historical/Archived**
- **Canonical** vs **Reference-only**

**Goal:** Reduce cognitive load without losing audit history.

---

## Principles

1. **No deletion** — Archive or redirect, never lose context
2. **Elevate contracts** — `./ci/run.sh` and `./scripts/verify.sh` are policy-as-code
3. **Progress docs are authoritative** — `docs/progress/` is the single source of truth for "where we are"
4. **Drift guards** — Every doc has: Purpose, Owner, Last Updated, Status
5. **Index lists only active docs** — Archive is discoverable but not cluttering navigation
6. **Index-first rule** — New docs must be linked from `docs/00-INDEX.md` or explicitly placed under `_archive/` / `_reference/`

---

## File-by-File Consolidation Plan

### 1. Authoritative Index (`docs/00-INDEX.md`)

**Action:** Update to reflect P0 + P1.4 baseline and elevate contracts

**Changes:**
- Add **"Policy & Contracts"** section at the top (before Quick Start)
  - `./ci/run.sh` — Local CI entrypoint (single source of truth)
  - `./scripts/verify.sh` — Verification script (encodes invariants)
  - `ci/README.md` — CI documentation
- Add **"Progress Tracking (Authoritative)"** section
  - `docs/progress/00-STATUS.md` — Current phase, blockers, next actions
  - `docs/progress/01-CHANGELOG-WORK.md` — Development changelog
  - `docs/progress/02-OPEN-QUESTIONS.md` — Open questions and decisions
  - `docs/progress/03-TEST-RUNS.md` — Test run log (canonical "what ran")
  - `docs/progress/04-PARITY-MATRIX.md` — iOS/Android parity tracking
  - `docs/progress/05-CHATGPT-FEEDBACK-PACKAGE.md` — AI collaboration package
- Update "Last Updated" to 2025-12-22
- Add "Baseline Tag" reference: `v1.0.11-p0-p1.4-complete`

**Status:** Active (update, don't archive)

---

### 2. Progress Docs (`docs/progress/`)

**Action:** Add drift guard headers to all progress docs

**Files to update:**
- `00-STATUS.md` — Already has Last Updated, add Purpose/Owner/Status
- `01-CHANGELOG-WORK.md` — Add standard header
- `02-OPEN-QUESTIONS.md` — Add standard header
- `03-TEST-RUNS.md` — Add standard header
- `04-PARITY-MATRIX.md` — Add standard header
- `05-CHATGPT-FEEDBACK-PACKAGE.md` — Already has Last Updated, add Purpose/Owner/Status

**Header template:**
```markdown
**Purpose:** [One sentence describing what this doc is for]
**Owner:** Development Team
**Last Updated:** 2025-12-22
**Status:** active|archived
```

**Status:** Active (enhance, don't archive)

---

### 3. Consolidation Artifacts (`docs/CONSOLIDATION_*.md`)

**Action:** Archive with pointer

**Files:**
- `docs/CONSOLIDATION_COMPLETE.md` — Move to `docs/_archive/2025-12-16-consolidation/`
- `docs/CONSOLIDATION_SOURCE_MAP.md` — Move to `docs/_archive/2025-12-16-consolidation/`

**Replacement:** Add note in `docs/00-INDEX.md` under "Archive Documentation":
> Historical consolidation artifacts from 2025-12-16 are preserved in `docs/_archive/2025-12-16-consolidation/`. See `CONSOLIDATION_SOURCE_MAP.md` for complete file mapping.

**Status:** Archive (preserve, don't delete)

---

### 4. Duplicate/Overlapping Docs

#### 4.1 Testing Quick References

**Files:**
- `docs/testing/QUICK_REFERENCE.md` — Keep as canonical
- `docs/testing/QUICK_REFERENCE_V2.md` — Archive or merge

**Action:**
- If `QUICK_REFERENCE_V2.md` has unique content → Merge into `QUICK_REFERENCE.md`, then archive V2
- If `QUICK_REFERENCE_V2.md` is superseded → Archive with pointer in `QUICK_REFERENCE.md`

**Status:** Review and consolidate

---

#### 4.2 Integration Refactor Notes

**Files:**
- `docs/integration/REFACTOR_NOTES.md` — Keep as canonical
- `docs/integration/REFACTOR_NOTES_QUICK_START.md` — Check if duplicate
- `docs/integration/REFACTOR_ANALYSIS.md` — Check if duplicate

**Action:**
- Review for overlap
- If duplicates → Archive with pointer
- If unique → Keep all, add cross-references

**Status:** Review and consolidate

---

#### 4.3 iOS Implementation Checklists

**Files:**
- `docs/platform/ios/IMPLEMENTATION_CHECKLIST.md` — Keep as canonical
- `docs/platform/ios/IOS_IMPLEMENTATION_CHECKLIST.md` — Check if duplicate
- `docs/platform/ios/IMPLEMENTATION_CHECKLIST_LEGACY.md` — Archive (already marked legacy)

**Action:**
- If `IOS_IMPLEMENTATION_CHECKLIST.md` duplicates `IMPLEMENTATION_CHECKLIST.md` → Archive with pointer
- `IMPLEMENTATION_CHECKLIST_LEGACY.md` → Move to `docs/_archive/2025-legacy-doc/`

**Status:** Review and consolidate

---

#### 4.4 Deployment Docs

**Files:**
- `docs/deployment-guide.md` — Keep as canonical (if exists)
- `docs/DEPLOYMENT_GUIDE.md` — Check if duplicate
- `docs/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
- `docs/DEPLOYMENT_SUMMARY.md` — Keep (complementary)

**Action:**
- If `deployment-guide.md` and `DEPLOYMENT_GUIDE.md` are duplicates → Keep one, archive other
- Ensure all deployment docs are cross-referenced

**Status:** Review and consolidate

---

### 5. AI Artifacts (`docs/ai/`)

**Action:** Add drift guard headers, clarify purpose

**Files:**
- All files in `docs/ai/` should have:
  - **Purpose:** AI collaboration artifacts (not product documentation)
  - **Status:** active|reference-only

**Status:** Active (enhance, don't archive)

---

### 6. Platform Docs (`docs/platform/`)

**Action:** Add drift guard headers, ensure no duplicates

**Status:** Active (enhance, don't archive)

---

### 7. Testing Docs (`docs/testing/`)

**Action:** Add drift guard headers, consolidate duplicates

**Status:** Active (enhance, consolidate duplicates)

---

### 8. Archive Structure

**Current:** `docs/archive/2025-legacy-doc/`

**Action:** Create new archive for P1.5:
- `docs/_archive/2025-12-16-consolidation/` — Consolidation artifacts
- Keep `docs/archive/2025-legacy-doc/` as-is (historical)

**Status:** Create new archive directory

---

## Implementation Steps

### Step 1: Update Index (High Priority)

1. Update `docs/00-INDEX.md`:
   - Add "Policy & Contracts" section
   - Add "Progress Tracking (Authoritative)" section
   - Update Last Updated to 2025-12-22
   - Add Baseline Tag reference

**Exit Criteria:** Index clearly elevates contracts and progress docs

---

### Step 2: Add Drift Guards (High Priority)

1. Add standard headers to all `docs/progress/*.md` files
2. Add standard headers to key platform/testing docs

**Exit Criteria:** All progress docs have Purpose/Owner/Last Updated/Status

---

### Step 3: Archive Consolidation Artifacts (Medium Priority)

1. Create `docs/_archive/2025-12-16-consolidation/`
2. Move `CONSOLIDATION_COMPLETE.md` and `CONSOLIDATION_SOURCE_MAP.md`
3. Add pointer in index

**Exit Criteria:** Consolidation artifacts archived, index updated

---

### Step 4: Review and Consolidate Duplicates (Medium Priority)

1. Review testing quick references (merge or archive)
2. Review integration refactor notes (merge or archive)
3. Review iOS implementation checklists (merge or archive)
4. Review deployment docs (merge or archive)

**Exit Criteria:** No duplicate content, all unique content preserved

---

### Step 5: Document Contracts Explicitly (Low Priority)

1. Ensure `ci/README.md` clearly states: "This is policy-as-code"
2. Add note in `docs/00-INDEX.md` that `./ci/run.sh` is the CI contract

**Exit Criteria:** Contracts are clearly documented as policy

---

## Success Criteria

- [ ] `docs/00-INDEX.md` elevates contracts and progress docs
- [ ] All progress docs have drift guard headers
- [ ] Consolidation artifacts archived with pointers
- [ ] Duplicate docs consolidated (merged or archived with pointers)
- [ ] No information loss (everything preserved or redirected)
- [ ] Index lists only active docs (archive discoverable but not cluttering)

---

## Risk Mitigation

**Risk:** Breaking internal links
**Mitigation:** Use redirects/pointers, don't delete files

**Risk:** Losing context
**Mitigation:** Archive with clear headers, preserve original paths in archive

**Risk:** Index becomes outdated
**Mitigation:** Add "Last Updated" to index, make it part of progress doc updates

---

## Timeline

**Estimated Effort:** 2-3 hours
- Step 1: 30 min
- Step 2: 45 min
- Step 3: 15 min
- Step 4: 60 min (review-heavy)
- Step 5: 15 min

**Dependencies:** None (can proceed immediately)

---

**Last Updated:** 2025-12-22  
**Status:** Ready for Implementation  
**Next Action:** Proceed with Step 1 (Update Index)