dfb99259d9
Updated docs/progress/00-STATUS.md to explicitly mark it as the canonical baseline authority. All other docs should reference this file for baseline information to prevent drift. This completes the baseline tag drift fix recommended in the consolidated review. Verification: - Status doc marked as canonical authority ✅ - Index doc references canonical baseline ✅
194 lines
10 KiB
Markdown
194 lines
10 KiB
Markdown
# Progress Status
|
|
|
|
**Purpose:** Single source of truth for current project status, phase completion, blockers, and next actions.
|
|
**Owner:** Development Team
|
|
**Last Updated:** 2025-12-23
|
|
**Status:** active
|
|
**Baseline Tag:** `v1.0.11-p3-complete` (canonical baseline authority)
|
|
|
|
---
|
|
|
|
## Current Phase
|
|
|
|
**P3: Performance, Observability & Developer Experience** - Performance optimization, enhanced observability, developer experience improvements, and documentation polish
|
|
|
|
**Status:** ✅ Complete — Tagged as baseline: `v1.0.11-p3-complete`
|
|
|
|
**What This Baseline Includes:**
|
|
- ✅ P0: Publish safety & CI hardening (packaging, exports, CI debuggability)
|
|
- ✅ P1.4: Shared core types module (errors/enums/contracts/events/guards)
|
|
- ✅ P1.5: Documentation consolidation (authoritative index, drift guards, archive standardization, contracts as policy)
|
|
- ✅ P2.6: Type safety cleanup (zero `any` except documented TS mixin limitation)
|
|
- ✅ P2.7: System invariants documentation (SYSTEM_INVARIANTS.md created)
|
|
- ✅ P2.1: Schema versioning strategy (iOS explicit version tracking in CoreData metadata)
|
|
- ✅ P2.2: Combined edge case tests (3 resilience scenarios: DST + duplicate + cold start, rollover + duplicate + cold start, schema version + cold start)
|
|
- ✅ Core module purity enforcement (platform import blocking, export validation)
|
|
- ✅ Consumer migration complete (observability, definitions, web use core types)
|
|
- ✅ All invariants enforced in tooling (`verify.sh` + `ci/run.sh`)
|
|
|
|
---
|
|
|
|
## Last Verify Run
|
|
|
|
**Date:** 2025-12-22
|
|
**Result:** ✅ Publish-safety checks pass on Linux (TypeScript + build + pack checks); Android/iOS native builds skipped (expected)
|
|
**Local CI Command:** `./ci/run.sh` (wraps `./scripts/verify.sh`)
|
|
**Verification:**
|
|
- `./scripts/verify.sh` - All critical checks passed
|
|
- `npm pack --dry-run | grep -E "xcuserdata|xcuserstate|DerivedData|ios/App/"` - Empty (no forbidden files)
|
|
|
|
---
|
|
|
|
## Blockers
|
|
|
|
None currently.
|
|
|
|
---
|
|
|
|
## Completed This Week
|
|
|
|
- [x] Documentation consolidation (139 files organized)
|
|
- [x] Created progress tracking system
|
|
- [x] PHASE 1: Remove native code from src/android/ and src/ios/
|
|
- [x] PHASE 3: Single verification entrypoint (`scripts/verify.sh`)
|
|
- [x] PHASE 3: Created local CI entrypoint (`ci/run.sh`)
|
|
- [x] P0: Build/publish safety fixes (web.ts, podspec, markdown paths)
|
|
- [x] P0: iOS recovery tests (DailyNotificationRecoveryTests.swift)
|
|
- [x] P0.5: Packaging fixes (exports["./web"] paths, tightened "files" field, excluded xcuserdata/ios/App/)
|
|
- [x] Parity corrections: iOS rollover and persistence confirmed
|
|
- [x] P1.4: Shared core types module (errors/enums/contracts/events/guards)
|
|
- [x] P1.4: Core module consumer migration (observability.ts, definitions.ts, web.ts)
|
|
- [x] P1.4: Core module purity enforcement (platform import blocking, export validation)
|
|
- [x] P2.6: Type safety cleanup — eliminated all `any` usages except documented TS mixin limitation
|
|
- `vite-plugin.ts`: removed `any` return types (replaced with `UserConfig` and concrete transform return type)
|
|
- `PlatformServiceMixin.ts`: documented TS mixin `any[]` exception (TypeScript limitation, not design choice)
|
|
- Audit confirmed: zero `any` in codebase except intentional mixin pattern
|
|
- [x] P2.7: Created SYSTEM_INVARIANTS.md — single authoritative document naming and explaining all enforced invariants
|
|
- [x] P2.1: Schema versioning strategy — iOS explicit version tracking in CoreData metadata (observability contract, not migration gate)
|
|
- [x] P2.2: Combined edge case tests — 3 resilience test scenarios (DST + duplicate + cold start, rollover + duplicate + cold start, schema version + cold start)
|
|
- [x] P2.3: Android combined edge case tests — achieved parity with iOS P2.2
|
|
- Enabled Android test infrastructure (JUnit, Robolectric, Room testing)
|
|
- Created TestDBFactory with in-memory database and data injection helpers
|
|
- Implemented 3 combined test scenarios mirroring iOS P2.2
|
|
- [x] P1.5b: Moved iOS/App test harness out of published tree
|
|
- Moved `ios/App/` to `test-apps/ios-app-legacy/` (legacy test harness)
|
|
- Active test app remains at `test-apps/ios-test-app/`
|
|
- Verified `ios/App` no longer appears in npm package
|
|
- [x] P3.1: Performance optimization & metrics
|
|
- Created metrics contract infrastructure (src/core/metrics.ts)
|
|
- Instrumented recovery paths (Android + iOS) with timing
|
|
- Instrumented database operations (Android) with timing
|
|
- Created performance characteristics documentation (docs/PERFORMANCE.md)
|
|
- [x] P3.2: Enhanced observability
|
|
- Expanded event coverage (9 new event codes for recovery, database, state transitions, background tasks)
|
|
- Implemented structured metrics export (exportMetrics(), getMetricsSummary())
|
|
- Enhanced error context (logError() with structured error data)
|
|
- Added opt-in diagnostic mode (enableDiagnosticMode(), getDiagnosticInfo())
|
|
- [x] P3.3: Developer experience improvements
|
|
- Enhanced error messages with actionable guidance (ERROR_GUIDANCE constant)
|
|
- Added debug helpers (getDebugState() method)
|
|
- Type tightening (ScheduleWithStatus.status field)
|
|
- Integration examples (Quick Start, Common Patterns)
|
|
- [x] P3.4: Documentation polish
|
|
- Enhanced public API JSDoc (createSchedule, updateSchedule, deleteSchedule, enableSchedule)
|
|
- Created troubleshooting guide (docs/TROUBLESHOOTING.md)
|
|
- Created getting started guide (docs/GETTING_STARTED.md)
|
|
- Updated documentation index
|
|
- [x] TypeScript error fix
|
|
- Fixed JSDoc parse error caused by `*/` sequence in cron expression
|
|
- Changed cron expression to avoid JSDoc comment termination issue
|
|
- Removed problematic examples and fixed template literal syntax
|
|
- TypeScript now compiles successfully (0 errors)
|
|
- [x] ChatGPT feedback response - Priority 1 (Quick Wins)
|
|
- Version unification: Normalized all version headers to 1.0.11, created version check script
|
|
- Repo hygiene: Strengthened .gitignore, removed tracked build artifacts
|
|
- Created feedback response plan documentation
|
|
- [x] ChatGPT feedback response - Priority 2.2 (TODO Classification)
|
|
- Classified 34 TODOs: 7 Must Ship, 2 Nice-to-Have, 19 Future, 3 Stubs
|
|
- Created comprehensive TODO classification document
|
|
- Identified critical items needing immediate attention
|
|
- [x] ChatGPT feedback response - Priority 3 (CI Workflows)
|
|
- Created GitHub Actions workflows (.github/workflows/ci.yml)
|
|
- Node/TS, Android, iOS jobs with graceful fallbacks
|
|
- Ready for merge gates (requires GitHub repo settings)
|
|
- [x] ChatGPT feedback response - Priority 4 (Packaging)
|
|
- Added packages/*/dist/ to .gitignore
|
|
- Prevents committing workspace build artifacts
|
|
- [x] ChatGPT feedback response - Priority 5 (Documentation)
|
|
- Enhanced README with Quick Start links, Compatibility Matrix, Behavioral Contracts
|
|
- All requested documentation improvements complete
|
|
|
|
---
|
|
|
|
## Next Actions (Max 5)
|
|
|
|
1. **Review P3 completion** - All P3 items complete, ready for baseline tag
|
|
2. **Consider next phase** - P3 complete, foundation ready for new features
|
|
|
|
---
|
|
|
|
## Known Gaps (Parity)
|
|
|
|
See [04-PARITY-MATRIX.md](./04-PARITY-MATRIX.md) for detailed parity tracking.
|
|
|
|
**Summary:**
|
|
- iOS persistence: ✅ Implemented (CoreData + SQLite)
|
|
- iOS rollover: ✅ Implemented (NotificationCenter pattern)
|
|
- iOS recovery testing: ✅ Implemented (DailyNotificationRecoveryTests.swift)
|
|
- iOS reboot recovery: N/A (iOS handles automatically)
|
|
- Storage schema versioning: ✅ Explicit (CoreData metadata tracking, P2.1 complete)
|
|
|
|
---
|
|
|
|
## Phase Status
|
|
|
|
| Phase | Priority | Status | Notes |
|
|
|-------|----------|--------|-------|
|
|
| PHASE 1 | P0.1 | ✅ Complete | Repo hygiene + packaging |
|
|
| PHASE 2 | P0.2 | ✅ Complete | iOS persistence parity (CoreData + SQLite confirmed) |
|
|
| PHASE 3 | P0.3 | ✅ Complete | Verification entrypoint + local CI |
|
|
| **P0 Phase** | **P0** | **✅ Complete** | **Publish safety & CI hardening (packaging, exports, CI debuggability)** |
|
|
| PHASE 4 | P1.4 | ✅ Complete | Shared core types module (errors/enums/contracts/events/guards) |
|
|
| PHASE 5 | P1.5 | ✅ Complete | Docs consolidation (authoritative index, drift guards, archive standardization, contracts as policy) |
|
|
| PHASE 6 | P2.6 | ✅ Complete | Type safety cleanup (zero `any` except documented TS mixin limitation) |
|
|
| PHASE 7 | P2.7 | ✅ Complete | System invariants doc (SYSTEM_INVARIANTS.md created) |
|
|
| PHASE 8 | P2.1 | ✅ Complete | Schema versioning strategy (iOS explicit version tracking) |
|
|
| PHASE 9 | P2.2 | ✅ Complete | Combined edge case tests (3 resilience scenarios) |
|
|
| PHASE 10 | P2.3 | ✅ Complete | Android combined edge case tests (parity with iOS P2.2) |
|
|
|
|
---
|
|
|
|
**Maintained By:** Development Team
|
|
**Update Frequency:** After each phase completion or significant change
|
|
|
|
---
|
|
|
|
## Packaging Invariants
|
|
|
|
**Policy:** Packaging is controlled primarily by `package.json.files` (whitelist). `.npmignore` is secondary.
|
|
|
|
**Required Checks:**
|
|
- `npm pack --dry-run | grep -E "xcuserdata|xcuserstate|DerivedData|ios/App/"` must remain **empty**
|
|
- CI must fail if forbidden files appear in package
|
|
- `exports["./web"]` paths must match actual build artifacts (`dist/esm/web.{js,d.ts}`)
|
|
|
|
**Verification:** Run `./ci/run.sh` (or `make ci`) before any publish - it includes forbidden files check.
|
|
|
|
**Local CI Policy:** `./ci/run.sh` is the **single source of truth** for CI. All publishing/releasing must be gated by `./ci/run.sh`. See `ci/README.md` for details.
|
|
|
|
**Critical Invariant:** Any CI or release gate MUST call `./ci/run.sh` (not `npm run build` directly), because `verify.sh` encodes packaging and core-purity invariants that must be checked before publish.
|
|
|
|
**Git Hook:** Pre-push hook available at `githooks/pre-push` (setup: `git config core.hooksPath githooks`). Calls `./ci/run.sh`.
|
|
|
|
**Baseline Tag:** `v1.0.11-p3-complete` — This tag represents P3 completion (performance optimization, enhanced observability, developer experience improvements, and documentation polish). Use as rollback anchor or reference point for future work.
|
|
|
|
**Previous Baselines:**
|
|
- `v1.0.11-p2.3-p1.5b-complete` — P2.x completion + test harness cleanup
|
|
- `v1.0.11-p2.3-complete` — P2.3 milestone (Android parity achieved)
|
|
- `v1.0.11-p2-complete` — P2.x milestone (schema versioning + iOS combined tests)
|
|
- `v1.0.11-p0-p1.4-p1.5-p2.6-p2.7-complete` — Foundation + type safety milestone
|
|
- `v1.0.11-p0-p1.4-complete` — Foundation milestone (P0 publish safety, P1.4 core module, P1.5 docs consolidation)
|
|
|
|
**Type Safety Invariant:** Only allowed `any` in repo: TS mixin constructor pattern (`src/utils/PlatformServiceMixin.ts:258`), documented inline. All external boundaries use `unknown`, all data payloads use `Record<string, unknown>`.
|
|
|