feat(docs): complete P2.6 type safety cleanup and P2.7 system invariants
P2.6: Type Safety Cleanup - Replaced 'any' return types in vite-plugin.ts with concrete types (UserConfig, transform return type) - Documented TypeScript mixin 'any[]' exception in PlatformServiceMixin.ts - Audit confirmed: zero 'any' in codebase except documented TS mixin limitation - All external boundaries use 'unknown', all data payloads use 'Record<string, unknown>' P2.7: System Invariants Documentation - Created SYSTEM_INVARIANTS.md documenting all 6 enforced invariants - Added to docs/00-INDEX.md under Policy & Contracts section - Each invariant includes: What, Why, How, Where Progress Docs Updates: - Updated 00-STATUS.md: marked P2.6/P2.7 complete, added type safety invariant note - Updated 01-CHANGELOG-WORK.md: added 2025-12-22 entries for P2.6/P2.7 - Updated 03-TEST-RUNS.md: added P2.6 type safety audit test run - Updated P2-DESIGN.md: marked P2.6 acceptance criteria complete - Updated SYSTEM_INVARIANTS.md: added Type Safety Notes section Baseline Tag: - Created v1.0.11-p0-p1.4-p1.5-p2.6-p2.7-complete TypeScript compilation: ✅ PASSES Build: ✅ PASSES CI: ✅ All checks pass
This commit is contained in:
Matthew Raymer
292
docs/P1.5-CONSOLIDATION-PLAN.md
Normal file
292
docs/P1.5-CONSOLIDATION-PLAN.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 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)
|
||||
|
||||
Reference in New Issue
Block a user