daily-notification-plugin/doc/design/P1.5-CONSOLIDATION-PLAN.md

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 — doc/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 doc/00-INDEX.md or explicitly placed under _archive/ / _reference/

---

File-by-File Consolidation Plan

1. Authoritative Index (doc/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
  • doc/progress/00-STATUS.md — Current phase, blockers, next actions
  • doc/progress/01-CHANGELOG-WORK.md — Development changelog
  • doc/progress/02-OPEN-QUESTIONS.md — Open questions and decisions
  • doc/progress/03-TEST-RUNS.md — Test run log (canonical "what ran")
  • doc/progress/04-PARITY-MATRIX.md — iOS/Android parity tracking
  • doc/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 (doc/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:

**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 (doc/CONSOLIDATION_*.md)

Action: Archive with pointer

Files:

• doc/CONSOLIDATION_COMPLETE.md — Move to doc/_archive/2025-12-16-consolidation/
• doc/CONSOLIDATION_SOURCE_MAP.md — Move to doc/_archive/2025-12-16-consolidation/

Replacement: Add note in doc/00-INDEX.md under "Archive Documentation":

Historical consolidation artifacts from 2025-12-16 are preserved in doc/_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:

• doc/testing/QUICK_REFERENCE.md — Keep as canonical
• doc/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:

• doc/integration/REFACTOR_NOTES.md — Keep as canonical
• doc/integration/REFACTOR_NOTES_QUICK_START.md — Check if duplicate
• doc/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:

• doc/platform/ios/IMPLEMENTATION_CHECKLIST.md — Keep as canonical
• doc/platform/ios/IOS_IMPLEMENTATION_CHECKLIST.md — Check if duplicate
• doc/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 doc/_archive/2025-legacy-doc/

Status: Review and consolidate

---

4.4 Deployment Docs

Files:

• doc/deployment/deployment-guide.md — Keep as canonical (if exists)
• doc/deployment/DEPLOYMENT_CHECKLIST.md — Keep (complementary)
• doc/progress/DEPLOYMENT_SUMMARY.md — Keep (complementary)

Action:

• If deployment/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 (doc/ai/)

Action: Add drift guard headers, clarify purpose

Files:

• All files in doc/ai/ should have:
  • Purpose: AI collaboration artifacts (not product documentation)
  • Status: active|reference-only

Status: Active (enhance, don't archive)

---

6. Platform Docs (doc/platform/)

Action: Add drift guard headers, ensure no duplicates

Status: Active (enhance, don't archive)

---

7. Testing Docs (doc/testing/)

Action: Add drift guard headers, consolidate duplicates

Status: Active (enhance, consolidate duplicates)

---

8. Archive Structure

Current: doc/archive/2025-legacy-doc/

Action: Create new archive for P1.5:

• doc/_archive/2025-12-16-consolidation/ — Consolidation artifacts
• Keep doc/archive/2025-legacy-doc/ as-is (historical)

Status: Create new archive directory

---

Implementation Steps

Step 1: Update Index (High Priority)

1. Update doc/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 doc/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 doc/_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 doc/00-INDEX.md that ./ci/run.sh is the CI contract

Exit Criteria: Contracts are clearly documented as policy

---

Success Criteria

• doc/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)