6ad7ff5fe1
- Keep only index, getting-started, invariants, performance, troubleshooting, and file-organization-summary in docs/ root - Add docs/architecture/ (storage, database interfaces, native fetcher) - Add docs/deployment/ (deployment-guide, DEPLOYMENT_CHECKLIST) - Add docs/compliance/ (accessibility, legal, observability) - Move integration guides and host-app docs to docs/integration/ - Move design/planning and prefetch docs to docs/design/ - Move Android consuming-app and comparison docs to docs/platform/android/ - Move DEPLOYMENT_SUMMARY and TODO-CLASSIFICATION to docs/progress/ - Archive deprecated platform-capability-reference to docs/_archive/ - Point platform-capability links to alarms/01-platform-capability-reference.md - Update docs/00-INDEX.md with new sections and paths - Fix cross-references in README, deployment, progress, design, testing, and test-app docs - Remove one-off COMMIT_MESSAGE.txt
292 lines
8.5 KiB
Markdown
292 lines
8.5 KiB
Markdown
# 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/deployment-guide.md` — Keep as canonical (if exists)
|
|
- `docs/deployment/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
|
|
- `docs/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 (`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)
|
|
|