docs: Add P3 mechanical execution checklist

Created detailed, file-by-file, function-by-function execution plan for P3. Includes: - Exact files to modify - Exact functions to instrument - Exact event codes to add - Exact JSDoc patterns - Exact commands to run - Batch-by-batch execution plan Ready for Cursor execution after approval.
2025-12-23 05:10:16 +00:00
parent 9767f7a5da
commit 1591d7ab89
1 changed files with 835 additions and 0 deletions
--- a/docs/progress/P3-EXECUTION-CHECKLIST.md
+++ b/docs/progress/P3-EXECUTION-CHECKLIST.md
@@ -0,0 +1,835 @@
 # P3 Execution Checklist — Mechanical Step-by-Step
 **Purpose:** Exact, file-by-file, function-by-function execution plan for P3 work.  
 **Owner:** Development Team  
 **Last Updated:** 2025-12-22  
 **Status:** execution-ready  
 **Baseline:** `v1.0.11-p2.3-p1.5b-complete`
 ---
 ## 0) Non-Negotiable Invariants (DO NOT BREAK)
 **Before every batch:**
 - [ ] Run `./ci/run.sh` and verify all checks pass
 - [ ] Verify `npm pack --dry-run | grep -E "xcuserdata|xcuserstate|DerivedData|ios/App/"` returns empty
 - [ ] Verify no platform imports in `src/core/` (grep for `@capacitor|react|fs|path|os`)
 - [ ] Verify `package.json.exports` matches build artifacts
 - [ ] Verify new docs are linked in `docs/00-INDEX.md` or placed in `docs/_archive/`
 **After every batch:**
 - [ ] Run `./ci/run.sh` — **STOP IF FAILS**
 - [ ] Update progress docs if applicable
 - [ ] Commit with clear message
 ---
 ## P3.1 — Performance Optimization & Metrics
 ### Batch 1: Add Metrics Collection Infrastructure
 **Files to create/modify:**
 1. **`src/core/metrics.ts`** (NEW FILE)
   ```typescript
   // Exact structure:
   export interface PerformanceMetric {
     operation: string;
     duration: number;
     timestamp: number;
     success: boolean;
     metadata?: Record<string, unknown>;
   }
   export interface MetricsCollector {
     record(metric: PerformanceMetric): void;
     getMetrics(): PerformanceMetric[];
     clear(): void;
   }
   // Lightweight in-memory collector (no deps)
   export class InMemoryMetricsCollector implements MetricsCollector {
     private metrics: PerformanceMetric[] = [];
     private maxMetrics = 100;
     record(metric: PerformanceMetric): void {
       this.metrics.push(metric);
       if (this.metrics.length > this.maxMetrics) {
         this.metrics = this.metrics.slice(-this.maxMetrics);
       }
     }
     getMetrics(): PerformanceMetric[] {
       return [...this.metrics];
     }
     clear(): void {
       this.metrics = [];
     }
   }
   ```
 2. **`src/core/index.ts`** (UPDATE)
   - Add export: `export * from './metrics';`
 **Verification:**
 - [ ] `npm run build` succeeds
 - [ ] `./ci/run.sh` passes
 - [ ] No new dependencies added
 ---
 ### Batch 2: Instrument Hot Paths — Scheduling
 **Files to modify:**
 1. **`src/web.ts`** — `createSchedule()` method
   - **Location:** Find `async createSchedule(input: CreateScheduleInput)`
   - **Add before method:**
     ```typescript
     const startTime = performance.now();
     ```
   - **Add after success (before return):**
     ```typescript
     const duration = performance.now() - startTime;
     this.observability?.logEvent('INFO', EVENT_CODES.SCHEDULE_UPDATE, 
       `Schedule created: ${result.schedule.id}`, 
       { scheduleId: result.schedule.id, duration });
     ```
   - **Add after error (in catch):**
     ```typescript
     const duration = performance.now() - startTime;
     this.observability?.logEvent('ERROR', EVENT_CODES.SCHEDULE_UPDATE, 
       `Schedule creation failed`, 
       { error: error.message, duration });
     ```
 2. **`src/web.ts`** — `updateSchedule()` method
   - **Same pattern:** Add timing before, log after (success/error)
 3. **`src/web.ts`** — `deleteSchedule()` method
   - **Same pattern:** Add timing before, log after (success/error)
 **Verification:**
 - [ ] TypeScript compiles (`npm run build`)
 - [ ] `./ci/run.sh` passes
 - [ ] No behavior changes (tests still pass)
 ---
 ### Batch 3: Instrument Hot Paths — Recovery
 **Files to modify:**
 1. **Android: `android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt`**
   - **Function:** `performColdStartRecovery()`
   - **Add at start:**
     ```kotlin
     val startTime = System.currentTimeMillis()
     ```
   - **Add before return:**
     ```kotlin
     val duration = System.currentTimeMillis() - startTime
     Log.i(TAG, "Cold start recovery completed: duration=${duration}ms, missed=$missedCount, rescheduled=$rescheduledCount")
     ```
 2. **Android: `android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt`**
   - **Function:** `performForceStopRecovery()`
   - **Same pattern:** Add timing, log duration
 3. **iOS: `ios/Plugin/DailyNotificationReactivationManager.swift`**
   - **Function:** `performColdStartRecovery()`
   - **Add at start:**
     ```swift
     let startTime = Date()
     ```
   - **Add before return:**
     ```swift
     let duration = Date().timeIntervalSince(startTime) * 1000 // ms
     os_log("Cold start recovery completed: duration=%.0fms, missed=%d, rescheduled=%d", 
            log: .default, type: .info, duration, missedCount, rescheduledCount)
     ```
 **Verification:**
 - [ ] Android builds (`cd test-apps/android-test-app && ./gradlew :daily-notification-plugin:build`)
 - [ ] iOS builds (if macOS available)
 - [ ] `./ci/run.sh` passes
 ---
 ### Batch 4: Instrument Hot Paths — Database Operations
 **Files to modify:**
 1. **Android: `android/src/main/java/com/timesafari/dailynotification/DatabaseSchema.kt`**
   - **Find:** Room DAO methods (e.g., `getEnabled()`, `getById()`)
   - **Add timing wrapper** (if possible without breaking Room contracts):
     ```kotlin
     // For critical queries, add timing in calling code, not DAO
     // Document in comments: "Timing measured in ReactivationManager"
     ```
 2. **Android: `android/src/main/java/com/timesafari/dailynotification/ReactivationManager.kt`**
   - **Function:** `runBootRecovery()`
   - **Add timing around DB query:**
     ```kotlin
     val dbStartTime = System.currentTimeMillis()
     val enabledSchedules = try {
       db.scheduleDao().getEnabled()
     } catch (e: Exception) {
       Log.e(TAG, "Failed to load schedules from DB", e)
       emptyList()
     } finally {
       val dbDuration = System.currentTimeMillis() - dbStartTime
       Log.d(TAG, "Database query duration: ${dbDuration}ms, schedules=${enabledSchedules.size}")
     }
     ```
 **Verification:**
 - [ ] Android builds
 - [ ] `./ci/run.sh` passes
 - [ ] No database contract violations
 ---
 ### Batch 5: Document Performance Characteristics
 **Files to create:**
 1. **`docs/PERFORMANCE.md`** (NEW FILE)
   ```markdown
   # Performance Characteristics
   ## Expected Operation Times
   - Schedule creation: < 50ms (typical), < 100ms (p95)
   - Schedule update: < 50ms (typical), < 100ms (p95)
   - Cold start recovery: < 500ms (typical), < 1000ms (p95)
   - Database query (getEnabled): < 50ms (typical), < 100ms (p95)
   ## Memory Footprint
   - In-memory metrics: ~10KB per 100 metrics
   - Event logs: ~5KB per 100 events
   - Total overhead: < 100KB (development mode)
   ## Platform-Specific Considerations
   - iOS: Background task time limits (~30 seconds)
   - Android: WorkManager execution time limits (flexible)
   - Web: No background execution limits
   ```
 2. **`docs/00-INDEX.md`** (UPDATE)
   - Add link: `- [PERFORMANCE.md](./PERFORMANCE.md) — Performance characteristics and benchmarks`
 **Verification:**
 - [ ] File created and linked
 - [ ] `./ci/run.sh` passes
 ---
 ### P3.1 Acceptance Checklist
 - [ ] Metrics collection infrastructure exists (`src/core/metrics.ts`)
 - [ ] Hot paths instrumented (scheduling, recovery, DB operations)
 - [ ] Performance characteristics documented (`docs/PERFORMANCE.md`)
 - [ ] `./ci/run.sh` green
 - [ ] No new dependencies
 - [ ] No behavior changes (tests pass)
 ---
 ## P3.2 — Enhanced Observability
 ### Batch 1: Expand Event Logging Coverage
 **Files to modify:**
 1. **`src/core/events.ts`** — Add missing event codes
   ```typescript
   // Add to EVENT_CODES object:
   RECOVERY_START: 'DNP-RECOVERY-START',
   RECOVERY_COMPLETE: 'DNP-RECOVERY-COMPLETE',
   RECOVERY_ERROR: 'DNP-RECOVERY-ERROR',
   DB_QUERY_START: 'DNP-DB-QUERY-START',
   DB_QUERY_COMPLETE: 'DNP-DB-QUERY-COMPLETE',
   DB_QUERY_ERROR: 'DNP-DB-QUERY-ERROR',
   STATE_TRANSITION: 'DNP-STATE-TRANSITION',
   BACKGROUND_TASK_START: 'DNP-BG-TASK-START',
   BACKGROUND_TASK_COMPLETE: 'DNP-BG-TASK-COMPLETE',
   ```
 2. **`src/observability.ts`** — Add recovery event logging
   - **Function:** `logEvent()` (already exists, no changes needed)
   - **Add helper method:**
     ```typescript
     logRecovery(operation: string, result: { success: boolean; missed?: number; rescheduled?: number; errors?: number; duration?: number }): void {
       const level = result.success ? 'INFO' : 'ERROR';
       this.logEvent(level, EVENT_CODES.RECOVERY_COMPLETE, 
         `Recovery ${operation} completed`, 
         { operation, ...result });
     }
     ```
 **Verification:**
 - [ ] TypeScript compiles
 - [ ] `./ci/run.sh` passes
 - [ ] Event codes are exported from `src/core/index.ts`
 ---
 ### Batch 2: Add Structured Metrics Export
 **Files to modify:**
 1. **`src/observability.ts`** — Add export method
   ```typescript
   /**
    * Export metrics as JSON
    * @returns JSON string of all metrics
    */
   exportMetrics(): string {
     return JSON.stringify({
       performance: this.performanceMetrics,
       user: this.userMetrics,
       platform: this.platformMetrics,
       events: this.eventLogs.slice(0, 100), // Last 100 events
       exportedAt: Date.now()
     }, null, 2);
   }
   /**
    * Get metrics summary (lightweight)
    * @returns Summary object
    */
   getMetricsSummary(): {
     eventCount: number;
     successRate: number;
     avgFetchTime: number;
     avgNotifyTime: number;
   } {
     const fetchTimes = this.performanceMetrics.fetchTimes;
     const notifyTimes = this.performanceMetrics.notifyTimes;
     const total = this.performanceMetrics.successCount + this.performanceMetrics.failureCount;
     return {
       eventCount: this.eventLogs.length,
       successRate: total > 0 ? this.performanceMetrics.successCount / total : 0,
       avgFetchTime: fetchTimes.length > 0 
         ? fetchTimes.reduce((a, b) => a + b, 0) / fetchTimes.length 
         : 0,
       avgNotifyTime: notifyTimes.length > 0
         ? notifyTimes.reduce((a, b) => a + b, 0) / notifyTimes.length
         : 0
     };
   }
   ```
 2. **`src/definitions.ts`** — Add to plugin interface (if needed)
   - Check if `DailyNotificationPlugin` interface needs `exportMetrics()` method
   - If yes, add: `exportMetrics(): Promise<{ metrics: string }>;`
 **Verification:**
 - [ ] TypeScript compiles
 - [ ] `./ci/run.sh` passes
 - [ ] JSON export is valid JSON
 ---
 ### Batch 3: Improve Error Context
 **Files to modify:**
 1. **`src/core/errors.ts`** — Enhance error class
   ```typescript
   // Find DailyNotificationError class
   // Add method:
   toJSON(): Record<string, unknown> {
     return {
       code: this.code,
       message: this.message,
       cause: this.cause ? String(this.cause) : undefined,
       stack: this.stack,
       timestamp: Date.now()
     };
   }
   ```
 2. **`src/observability.ts`** — Enhance error logging
   ```typescript
   // In logEvent(), if level === 'ERROR' and data contains error:
   logError(eventCode: string, message: string, error: Error, context?: Record<string, unknown>): void {
     const errorData: Record<string, unknown> = {
       error: error.message,
       errorCode: error instanceof DailyNotificationError ? error.code : undefined,
       stack: error.stack,
       ...context
     };
     this.logEvent('ERROR', eventCode, message, errorData);
   }
   ```
 **Verification:**
 - [ ] TypeScript compiles
 - [ ] `./ci/run.sh` passes
 - [ ] Error context includes stack traces
 ---
 ### Batch 4: Add Diagnostic Mode
 **Files to modify:**
 1. **`src/observability.ts`** — Add diagnostic flag
   ```typescript
   private diagnosticMode = false;
   /**
    * Enable diagnostic mode (verbose logging)
    */
   enableDiagnosticMode(): void {
     this.diagnosticMode = true;
     this.logEvent('INFO', EVENT_CODES.METRICS_RESET, 'Diagnostic mode enabled');
   }
   /**
    * Disable diagnostic mode
    */
   disableDiagnosticMode(): void {
     this.diagnosticMode = false;
   }
   /**
    * Check if diagnostic mode is enabled
    */
   isDiagnosticMode(): boolean {
     return this.diagnosticMode;
   }
   ```
 2. **`src/definitions.ts`** — Add to plugin interface
   ```typescript
   // Add to DailyNotificationPlugin:
   enableDiagnosticMode(): Promise<void>;
   disableDiagnosticMode(): Promise<void>;
   getDiagnosticInfo(): Promise<{ metrics: string; eventCount: number }>;
   ```
 **Verification:**
 - [ ] TypeScript compiles
 - [ ] `./ci/run.sh` passes
 - [ ] Diagnostic mode can be toggled
 ---
 ### P3.2 Acceptance Checklist
 - [ ] Event logging coverage expanded (new event codes added)
 - [ ] Structured metrics export implemented (`exportMetrics()`)
 - [ ] Error context improved (stack traces, state snapshots)
 - [ ] Diagnostic mode added (toggle, info export)
 - [ ] `./ci/run.sh` green
 - [ ] No new dependencies
 ---
 ## P3.3 — Developer Experience Improvements
 ### Batch 1: Improve Error Messages
 **Files to modify:**
 1. **`src/core/errors.ts`** — Enhance error messages
   ```typescript
   // For each error code, add actionable guidance:
   // Example:
   PERMISSION_DENIED: {
     code: 'PERMISSION_DENIED',
     message: 'Notification permission denied',
     guidance: 'Request permission using requestPermission() before scheduling notifications',
     platformHints: {
       ios: 'Check Info.plist for notification permission description',
       android: 'Check AndroidManifest.xml for POST_NOTIFICATIONS permission'
     }
   }
   ```
 2. **`src/web.ts`** — Improve error handling
   - **Find:** `throwNotSupported()` method
   - **Enhance:**
     ```typescript
     private throwNotSupported(): never {
       throw new DailyNotificationError(
         ErrorCode.NOT_SUPPORTED,
         'This operation is not supported on the web platform',
         undefined,
         {
           guidance: 'Use native iOS or Android implementation for this feature',
           platform: 'web'
         }
       );
     }
     ```
 **Verification:**
 - [ ] TypeScript compiles
 - [ ] `./ci/run.sh` passes
 - [ ] Error messages are actionable
 ---
 ### Batch 2: Add Development Mode Helpers
 **Files to modify:**
 1. **`src/web.ts`** — Add debug helpers
   ```typescript
   /**
    * Get current plugin state (development only)
    * @internal
    */
   async getDebugState(): Promise<{
     schedules: Schedule[];
     configs: Config[];
     callbacks: Callback[];
     metrics: ReturnType<ObservabilityManager['getMetricsSummary']>;
   }> {
     if (process.env.NODE_ENV === 'production') {
       throw new DailyNotificationError(ErrorCode.NOT_SUPPORTED, 'Debug methods not available in production');
     }
     const schedules = await this.getSchedules();
     const configs = await this.getConfigs();
     const callbacks = await this.getCallbacks();
     const metrics = this.observability?.getMetricsSummary() || { eventCount: 0, successRate: 0, avgFetchTime: 0, avgNotifyTime: 0 };
     return {
       schedules: schedules.schedules,
       configs: configs.configs,
       callbacks: callbacks.callbacks,
       metrics
     };
   }
   ```
 **Verification:**
 - [ ] TypeScript compiles
 - [ ] `./ci/run.sh` passes
 - [ ] Debug methods only work in development
 ---
 ### Batch 3: Enhance TypeScript Types
 **Files to modify:**
 1. **`src/core/contracts.ts`** — Add discriminated unions where appropriate
   ```typescript
   // Example: Enhance ScheduleWithStatus
   export type ScheduleWithStatus = Schedule & {
     status: 'active' | 'paused' | 'error';
     nextRunAt: number | null;
     lastRunAt: number | null;
   } & (
     | { status: 'active'; nextRunAt: number }
     | { status: 'paused'; nextRunAt: null }
     | { status: 'error'; nextRunAt: null; error: string }
   );
   ```
 2. **`src/definitions.ts`** — Add JSDoc improvements
   ```typescript
   /**
    * Create a new notification schedule
    * 
    * @param input - Schedule configuration
    * @param input.id - Unique schedule identifier (required)
    * @param input.kind - Schedule type: 'notify' for notifications, 'fetch' for content fetching
    * @param input.cron - Cron expression (e.g., '0 9 * * *' for daily at 9 AM)
    * @param input.clockTime - Time of day in HH:mm format (alternative to cron)
    * @param input.enabled - Whether schedule is active (default: true)
    * @returns Created schedule with status
    * @throws {DailyNotificationError} If schedule creation fails
    * 
    * @example
    * ```typescript
    * const schedule = await DailyNotification.createSchedule({
    *   id: 'morning-notification',
    *   kind: 'notify',
    *   clockTime: '09:00',
    *   enabled: true
    * });
    * ```
    */
   createSchedule(input: CreateScheduleInput): Promise<{ schedule: ScheduleWithStatus }>;
   ```
 **Verification:**
 - [ ] TypeScript compiles
 - [ ] IntelliSense shows improved types
 - [ ] `./ci/run.sh` passes
 ---
 ### Batch 4: Expand Integration Examples
 **Files to create:**
 1. **`docs/examples/QUICK_START.md`** (NEW FILE)
   ```markdown
   # Quick Start Guide
   ## Minimal Working Example
   \`\`\`typescript
   import { DailyNotification } from '@timesafari/daily-notification-plugin';
   // 1. Request permission
   const { state } = await DailyNotification.requestPermission();
   if (state !== 'granted') {
     console.error('Permission denied');
     return;
   }
   // 2. Create schedule
   const { schedule } = await DailyNotification.createSchedule({
     id: 'daily-morning',
     kind: 'notify',
     clockTime: '09:00',
     enabled: true
   });
   // 3. Verify schedule
   const { schedules } = await DailyNotification.getSchedules();
   console.log('Active schedules:', schedules);
   \`\`\`
   ```
 2. **`docs/examples/COMMON_PATTERNS.md`** (NEW FILE)
   - Add patterns for: scheduling, recovery, error handling, platform-specific
 3. **`docs/00-INDEX.md`** (UPDATE)
   - Add section: `## Examples`
   - Link: `- [Quick Start](./examples/QUICK_START.md)`
   - Link: `- [Common Patterns](./examples/COMMON_PATTERNS.md)`
 **Verification:**
 - [ ] Examples are accurate and runnable
 - [ ] `./ci/run.sh` passes
 - [ ] Examples linked in index
 ---
 ### P3.3 Acceptance Checklist
 - [ ] Error messages improved (actionable, context-rich)
 - [ ] Development mode helpers added (`getDebugState()`)
 - [ ] TypeScript types enhanced (discriminated unions, JSDoc)
 - [ ] Integration examples expanded (quick-start, patterns)
 - [ ] `./ci/run.sh` green
 - [ ] No breaking changes
 ---
 ## P3.4 — Documentation Polish
 ### Batch 1: Complete API Documentation (JSDoc)
 **Files to modify (exact list):**
 1. **`src/definitions.ts`** — All public methods
   - `createSchedule()` — Add JSDoc (see P3.3 Batch 3 example)
   - `updateSchedule()` — Add JSDoc
   - `deleteSchedule()` — Add JSDoc
   - `getSchedules()` — Add JSDoc
   - `createConfig()` — Add JSDoc
   - `updateConfig()` — Add JSDoc
   - `deleteConfig()` — Add JSDoc
   - `getConfigs()` — Add JSDoc
   - `createCallback()` — Add JSDoc
   - `updateCallback()` — Add JSDoc
   - `deleteCallback()` — Add JSDoc
   - `getCallbacks()` — Add JSDoc
   - `requestPermission()` — Add JSDoc
   - `checkPermission()` — Add JSDoc
 2. **`src/core/contracts.ts`** — All interfaces
   - Add JSDoc to: `Schedule`, `Config`, `Callback`, `History`, `ContentCache`
 3. **`src/core/errors.ts`** — Error codes
   - Add JSDoc to `ErrorCode` enum values
   - Add JSDoc to `DailyNotificationError` class
 **Verification:**
 - [ ] All public APIs have JSDoc
 - [ ] JSDoc includes: params, returns, throws, examples
 - [ ] `npm run build` generates `.d.ts` files with JSDoc
 ---
 ### Batch 2: Add Troubleshooting Guides
 **Files to create:**
 1. **`docs/TROUBLESHOOTING.md`** (NEW FILE)
   ```markdown
   # Troubleshooting Guide
   ## Common Issues
   ### CI Failures
   **Problem:** `./ci/run.sh` fails
   **Solutions:**
   1. Check forbidden files: `npm pack --dry-run | grep -E "xcuserdata|xcuserstate|DerivedData|ios/App/"`
   2. Check core purity: `grep -r "@capacitor\|react\|fs\|path" src/core/`
   3. Check exports: `node -e "const p=require('./package.json'); console.log(p.exports)"`
   ### Packaging Failures
   **Problem:** `npm pack` includes forbidden files
   **Solution:** Update `package.json.files` whitelist
   ### Platform Test Failures
   **Problem:** Android/iOS tests fail
   **Solutions:**
   - Android: Run from test-app: `cd test-apps/android-test-app && ./gradlew :daily-notification-plugin:test`
   - iOS: Requires macOS + Xcode
   ```
 2. **`docs/00-INDEX.md`** (UPDATE)
   - Add link: `- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — Common issues and solutions`
 **Verification:**
 - [ ] Troubleshooting guide is comprehensive
 - [ ] `./ci/run.sh` passes
 - [ ] Guide linked in index
 ---
 ### Batch 3: Improve Onboarding Documentation
 **Files to create/modify:**
 1. **`docs/GETTING_STARTED.md`** (NEW FILE or UPDATE existing)
   ```markdown
   # Getting Started
   ## Step 1: Installation
   \`\`\`bash
   npm install @timesafari/daily-notification-plugin
   \`\`\`
   ## Step 2: Platform Setup
   - iOS: Add to `Info.plist` (see integration guide)
   - Android: Add to `AndroidManifest.xml` (see integration guide)
   ## Step 3: Basic Usage
   See [Quick Start](./examples/QUICK_START.md)
   ## Architecture Overview
   See [ARCHITECTURE.md](./ARCHITECTURE.md)
   ## Key Concepts
   - **Scheduling**: Recurring notification patterns
   - **Recovery**: Automatic rescheduling after app restart
   - **Persistence**: State survives app/OS restarts
   ```
 2. **`docs/00-INDEX.md`** (UPDATE)
   - Add link: `- [GETTING_STARTED.md](./GETTING_STARTED.md) — Step-by-step onboarding`
 **Verification:**
 - [ ] Getting started guide is clear
 - [ ] `./ci/run.sh` passes
 - [ ] Guide linked in index
 ---
 ### Batch 4: Add Migration Guides (if needed)
 **Files to create (only if breaking changes exist):**
 1. **`docs/MIGRATION.md`** (NEW FILE, only if needed)
   ```markdown
   # Migration Guide
   ## Version Upgrades
   ### v1.0.11 → v1.0.12
   No breaking changes.
   ### v1.0.10 → v1.0.11
   - Core module introduced: Use `@timesafari/daily-notification-plugin/core` for core types
   ```
 **Verification:**
 - [ ] Migration guide only created if needed
 - [ ] `./ci/run.sh` passes
 - [ ] Guide linked in index (if created)
 ---
 ### P3.4 Acceptance Checklist
 - [ ] API documentation complete (all public APIs have JSDoc)
 - [ ] Troubleshooting guides added (`docs/TROUBLESHOOTING.md`)
 - [ ] Onboarding documentation improved (`docs/GETTING_STARTED.md`)
 - [ ] Migration guides added (if needed)
 - [ ] Documentation index updated (`docs/00-INDEX.md`)
 - [ ] `./ci/run.sh` green
 ---
 ## P3 Close-out Checklist
 **When all P3 items are complete:**
 - [ ] Parity matrix updated (if any parity-related items added)
 - [ ] Progress docs updated:
  - [ ] `docs/progress/00-STATUS.md` — Mark P3 complete
  - [ ] `docs/progress/01-CHANGELOG-WORK.md` — Add P3 completion entry
  - [ ] `docs/progress/03-TEST-RUNS.md` — Add performance test results (if applicable)
 - [ ] `./ci/run.sh` green
 - [ ] Create baseline tag: `v1.0.11-p3-complete`
 - [ ] Push tag: `git push --tags`
 ---
 ## Execution Notes
 **Batch Discipline:**
 - Complete one batch at a time
 - Run `./ci/run.sh` after each batch
 - Commit after each batch (if desired) or after completing a full P3.x item
 **No New Dependencies:**
 - Use built-in APIs only (`performance.now()`, `Date.now()`, etc.)
 - No external metrics libraries
 - No external logging libraries
 **Testing:**
 - Existing tests must continue to pass
 - No new test infrastructure required (unless explicitly in acceptance criteria)
 **Documentation:**
 - All new docs must be linked in `docs/00-INDEX.md`
 - All docs must have drift guards (Purpose, Owner, Last Updated, Status)
 ---
 **Last Updated:** 2025-12-22  
 **Status:** Execution-ready (awaiting approval to begin)