@harness-engineering/cli 1.13.0 → 1.14.0

package/dist/agents/skills/gemini-cli/harness-mobile-patterns/SKILL.md

@@ -0,0 +1,326 @@
+# Harness Mobile Patterns
+
+> Advise on mobile platform lifecycle management, permission handling, deep linking, push notifications, and app store submission compliance. Covers iOS, Android, React Native, and Flutter with platform-specific best practices.
+
+## When to Use
+
+- When building or reviewing a mobile feature that involves permissions, deep links, or push notifications
+- When preparing a mobile application for App Store or Play Store submission
+- When auditing an existing mobile app for platform lifecycle and configuration correctness
+- NOT for mobile UI design patterns or component libraries (use harness-design-mobile)
+- NOT for mobile accessibility auditing (use harness-accessibility)
+- NOT for mobile performance profiling or bundle size analysis (use harness-perf)
+
+## Process
+
+### Phase 1: DETECT -- Identify Mobile Platform and Configuration
+
+1. **Resolve project root.** Use provided path or cwd.
+
+2. **Detect mobile platform and framework.** Scan for:
+   - **React Native:** `app.json`, `App.tsx`, `react-native.config.js`, `node_modules/react-native`
+   - **Flutter:** `pubspec.yaml`, `lib/main.dart`, `android/`, `ios/`
+   - **Native iOS:** `*.xcodeproj`, `*.xcworkspace`, `Info.plist`, `AppDelegate.swift`
+   - **Native Android:** `AndroidManifest.xml`, `build.gradle`, `*.kt` or `*.java` in `app/src/`
+   - **Expo:** `app.json` with `expo` key, `eas.json`, `expo-modules-autolinking`
+
+3. **Inventory platform configurations.** Read and catalog:
+   - **iOS:** `Info.plist` (permissions, URL schemes, associated domains), `Entitlements.plist`, provisioning profile references
+   - **Android:** `AndroidManifest.xml` (permissions, intent filters, deep links), `build.gradle` (target SDK, dependencies), `google-services.json`
+   - **React Native:** `app.json` (display name, bundle ID), native module links, Podfile
+   - **Flutter:** `pubspec.yaml` (dependencies), platform-specific configs under `ios/` and `android/`
+
+4. **Detect feature implementations.** Scan source code for:
+   - **Permissions:** `requestPermission`, `checkPermission`, `NSLocationWhenInUseUsageDescription`, `uses-permission`
+   - **Deep linking:** URL scheme handlers, universal link configuration, App Links verification, `Linking.addEventListener`
+   - **Push notifications:** Firebase Cloud Messaging setup, APNs configuration, notification handling code
+   - **Lifecycle:** `AppState.addEventListener`, `onPause/onResume`, `WidgetsBindingObserver`, `applicationDidEnterBackground`
+
+5. **Check build and signing configuration.** Verify:
+   - Bundle identifier / application ID consistency across configs
+   - Version number and build number format
+   - Signing configuration references (keystore for Android, certificates for iOS)
+   - Build variants (debug, release, staging)
+
+6. **Report detection summary:**
+   ```
+   Mobile Platform Detection:
+   Framework: React Native 0.73 (Expo managed workflow)
+   Platforms: iOS 15+ (deployment target), Android API 24+ (minSdkVersion)
+   Bundle ID: com.example.myapp (consistent across platforms)
+   Permissions: camera, photo library, push notifications, location (when in use)
+   Deep linking: URL scheme registered, universal links not configured
+   Push: Firebase Cloud Messaging (Android), APNs (iOS)
+   Build: 3 variants (debug, staging, release)
+   ```
+
+---
+
+### Phase 2: ANALYZE -- Evaluate Platform Patterns
+
+1. **Audit permission handling.** For each declared permission:
+   - Is the permission requested at the point of use (not at app launch)?
+   - Is there a pre-permission prompt explaining why it is needed?
+   - Is the denied state handled gracefully? (fallback UI, re-request with rationale)
+   - Is the permission usage description string clear and specific?
+   - **iOS:** Are `NSUsageDescription` strings present for every requested permission?
+   - **Android:** Is the runtime permission flow implemented for dangerous permissions (API 23+)?
+   - **EARS pattern:** When the user denies camera permission, the system shall display a fallback UI explaining why the camera is needed and offer a button to open Settings.
+
+2. **Audit deep linking.** Evaluate:
+   - **URL scheme:** Is a custom scheme registered? (`myapp://`) Are conflicts possible with other apps?
+   - **Universal Links (iOS):** Is the `apple-app-site-association` file configured? Is `applinks:` domain in entitlements?
+   - **App Links (Android):** Is the `intent-filter` with `autoVerify="true"` configured? Is `assetlinks.json` hosted?
+   - **Navigation:** Do deep links route to the correct screen? Is authentication state handled? (deep link to protected content when logged out)
+   - **Fallback:** What happens when the app is not installed? Is there a web fallback or app store redirect?
+
+3. **Audit push notification setup.** Evaluate:
+   - Is push token registration handled at the right time? (after permission granted, not at startup)
+   - Are notification payloads handled in all app states? (foreground, background, terminated)
+   - Is the notification tap handler routing to the correct screen?
+   - Are silent/background notifications handled separately from display notifications?
+   - **iOS:** Is the APNs environment correct? (sandbox for dev, production for release)
+   - **Android:** Are notification channels created for API 26+? Are channel importance levels appropriate?
+
+4. **Audit lifecycle management.** Check:
+   - Is app state change handled? (foreground, background, inactive/paused)
+   - Are WebSocket connections and location updates paused when backgrounded?
+   - Is local state persisted before backgrounding? (in-progress forms, drafts)
+   - Are long-running tasks configured for background execution? (iOS: background modes, Android: WorkManager)
+   - Is the splash screen / launch screen configured to avoid white flash?
+
+5. **Audit app store readiness.** Check:
+   - **iOS App Store:** Privacy nutrition labels match actual data collection, required screenshots and metadata
+   - **Google Play Store:** Data safety section accuracy, target API level compliance (Play requires API 34+)
+   - **Both:** Privacy policy URL configured, age rating appropriate, content declarations accurate
+   - **Version requirements:** Does the app meet minimum OS version requirements for store submission?
+
+6. **Classify findings by severity:**
+   - **Error:** Missing permission usage description (App Store rejection), deep link to authenticated content without auth check, push token sent to server without encryption
+   - **Warning:** Permissions requested at launch instead of point-of-use, missing universal link fallback, notification channels not created
+   - **Info:** Optional background mode not configured, missing pre-permission prompt, version number format suggestion
+
+---
+
+### Phase 3: ADVISE -- Recommend Platform Best Practices
+
+1. **Generate permission handling recommendations.** For each finding:
+   - Provide the platform-specific fix with code reference
+   - Show the recommended permission flow (request -> explain -> handle denial -> Settings redirect)
+   - Include usage description string recommendations that explain user benefit, not technical need
+   - Example: Instead of "This app needs camera access" use "Take photos to add to your project boards"
+
+2. **Generate deep linking setup guide.** Based on what is missing:
+   - **Universal Links:** Provide `apple-app-site-association` template, entitlement configuration, and server-side hosting instructions
+   - **App Links:** Provide `assetlinks.json` template, `intent-filter` XML, and verification steps
+   - **Deferred deep linking:** Recommend solutions for handling links when the app is not installed (Branch, Firebase Dynamic Links successor, or custom implementation)
+   - Include routing logic for handling authentication state during deep link navigation
+
+3. **Generate push notification checklist.** Provide:
+   - Platform-specific setup steps (FCM for Android, APNs for iOS)
+   - Notification handler implementation for all app states
+   - Channel creation code for Android API 26+
+   - Token refresh handling and server-side update logic
+   - Testing strategy (push notification testing is notoriously difficult)
+
+4. **Generate store submission checklist.** Provide:
+   - Privacy manifest requirements (iOS 17+: required reason APIs, tracking declaration)
+   - Data safety form guidance (Google Play: data collection, sharing, security practices)
+   - Screenshot and metadata requirements per platform
+   - Common rejection reasons and how to avoid them
+
+5. **Recommend lifecycle improvements.** Provide:
+   - State preservation patterns for the detected framework
+   - Background task configuration for long-running operations
+   - Memory management recommendations (clearing caches on memory warning)
+   - Network reconnection patterns after backgrounding
+
+---
+
+### Phase 4: VALIDATE -- Verify Configuration Completeness
+
+1. **Verify permission configuration completeness.** For each permission in code:
+   - Is the permission declared in the platform manifest? (Info.plist / AndroidManifest.xml)
+   - Is the runtime request implemented? (not just the manifest declaration)
+   - Is the denial handler implemented?
+   - Does the usage description match the actual use case?
+
+2. **Verify deep link routing.** For each registered deep link pattern:
+   - Does a route handler exist that matches the URL pattern?
+   - Is the handler accessible from all app states? (cold start, warm start, foreground)
+   - Are URL parameters validated before use?
+
+3. **Verify push notification flow.** End-to-end:
+   - Permission request -> token registration -> server-side storage -> notification receipt -> tap handling -> screen navigation
+   - Each step must be implemented, not just the first and last
+
+4. **Output mobile patterns report:**
+
+   ```
+   Mobile Patterns Report: [PASS/NEEDS_ATTENTION/FAIL]
+   Platform: React Native 0.73 (iOS + Android)
+
+   Permissions (4 declared):
+     camera: OK (point-of-use request, denial handled, description clear)
+     location: WARNING (requested at launch, should be point-of-use)
+     push: OK (requested after onboarding, token registered)
+     photo_library: ERROR (missing NSPhotoLibraryUsageDescription in Info.plist)
+
+   Deep Linking:
+     URL scheme: OK (myapp:// registered on both platforms)
+     Universal Links: NOT_CONFIGURED (recommended for iOS)
+     App Links: NOT_CONFIGURED (recommended for Android)
+     Auth handling: WARNING (deep link to /profile without auth check)
+
+   Push Notifications:
+     iOS (APNs): OK
+     Android (FCM): WARNING (no notification channels for API 26+)
+     Foreground handling: OK
+     Background handling: OK
+     Terminated handling: MISSING
+
+   Store Readiness:
+     iOS: NEEDS_ATTENTION (missing privacy nutrition labels for location)
+     Android: NEEDS_ATTENTION (target SDK 33, Play Store requires 34+)
+
+   ERRORS: 1 | WARNINGS: 4 | INFO: 2
+   ```
+
+5. **Cross-reference platform configs.** Verify iOS and Android configurations are consistent:
+   - Same deep link patterns registered on both platforms
+   - Same permissions requested on both platforms (where applicable)
+   - Same push notification handling on both platforms
+   - Version numbers aligned
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-mobile-patterns`** -- Primary command for mobile platform auditing.
+- **`harness validate`** -- Run after applying configuration changes to verify project health.
+- **`Glob`** -- Used to locate platform configs (Info.plist, AndroidManifest.xml), native modules, and framework files.
+- **`Grep`** -- Used to find permission requests, deep link handlers, notification setup, and lifecycle methods in source code.
+- **`Read`** -- Used to read platform manifests, entitlements, build configurations, and native module source.
+- **`Write`** -- Used to generate configuration templates, `apple-app-site-association` files, and store submission checklists.
+- **`Bash`** -- Used to check Xcode project settings, Gradle configurations, and run platform-specific validation commands.
+- **`emit_interaction`** -- Used to present the audit report and confirm recommendations before generating configuration changes.
+
+## Success Criteria
+
+- Mobile platform and framework are correctly detected with version information
+- All declared permissions are audited for request timing, denial handling, and description quality
+- Deep linking configuration is evaluated for both URL schemes and universal/app links
+- Push notification setup covers all app states (foreground, background, terminated)
+- Lifecycle management is evaluated for state preservation and background behavior
+- App store readiness is assessed against current submission requirements
+- Report provides platform-specific, actionable findings with code references
+
+## Examples
+
+### Example: React Native App with Expo
+
+```
+Phase 1: DETECT
+  Framework: React Native 0.73 (Expo SDK 50, managed workflow)
+  Platforms: iOS 16+, Android API 26+
+  Permissions: camera, notifications, location-when-in-use
+  Deep linking: expo-linking configured, no universal links
+  Push: expo-notifications with FCM
+
+Phase 2: ANALYZE
+  [MOB-ERR-001] app.json
+    Missing NSCameraUsageDescription -- will cause App Store rejection
+  [MOB-WARN-001] src/screens/HomeScreen.tsx:15
+    Location permission requested on mount, not when map feature is used
+  [MOB-WARN-002] No notification channel configuration for Android
+  [MOB-INFO-001] expo-linking handles deep links but no deferred deep link support
+
+Phase 3: ADVISE
+  Add to app.json plugins: ["expo-camera", { cameraPermission: "Take photos for your profile" }]
+  Move location request to MapScreen component
+  Add expo-notifications channel creation in App.tsx useEffect
+  Consider expo-linking with web fallback for deferred deep links
+
+Phase 4: VALIDATE
+  Permissions complete after fix: YES
+  Deep link routing covers auth state: NO (needs auth check)
+  Store readiness: iOS PASS (after fix), Android NEEDS_ATTENTION (target SDK)
+```
+
+### Example: Flutter App with Firebase
+
+```
+Phase 1: DETECT
+  Framework: Flutter 3.19, Dart 3.3
+  Platforms: iOS 14+, Android API 23+
+  Dependencies: firebase_messaging, firebase_dynamic_links, permission_handler
+  Permissions: camera, microphone, storage, notifications
+
+Phase 2: ANALYZE
+  [MOB-ERR-001] android/app/build.gradle
+    targetSdkVersion 33 -- Play Store requires 34+ for new submissions
+  [MOB-ERR-002] lib/services/push_service.dart
+    onMessageOpenedApp handler missing -- tapped notifications from background do nothing
+  [MOB-WARN-001] lib/main.dart
+    All 4 permissions requested in initState -- should be contextual
+  [MOB-WARN-002] ios/Runner/Info.plist
+    NSMicrophoneUsageDescription: "Microphone access" -- too vague
+
+Phase 3: ADVISE
+  Update targetSdkVersion to 34 and test for behavioral changes
+  Implement FirebaseMessaging.onMessageOpenedApp handler with navigation
+  Move permission requests to feature screens (camera on photo screen, mic on voice screen)
+  Update description: "Record voice messages to send to your team"
+
+Phase 4: VALIDATE
+  Config consistency iOS vs Android: 3/4 permissions aligned (storage is Android-only, OK)
+  Push flow complete after fix: YES (foreground + background + terminated)
+  Store readiness after fixes: iOS PASS, Android PASS
+```
+
+### Example: Native iOS App (Swift) Store Submission Audit
+
+```
+Phase 1: DETECT
+  Framework: Native iOS (Swift 5.9, Xcode 15)
+  Deployment target: iOS 16.0
+  Capabilities: push notifications, associated domains, HealthKit
+  Permissions: health-share, health-update, notifications, location-always
+
+Phase 2: ANALYZE
+  [MOB-ERR-001] Info.plist
+    Missing NSHealthShareUsageDescription for HealthKit read access
+  [MOB-ERR-002] Runner.entitlements
+    Associated domains list includes staging URL -- remove before production build
+  [MOB-WARN-001] AppDelegate.swift
+    Location-always permission requested without location-when-in-use fallback
+    Apple may reject: must request when-in-use first, then upgrade to always
+  [MOB-WARN-002] Privacy manifest (PrivacyInfo.xcprivacy) not present
+    Required for iOS 17+ submissions using required reason APIs
+
+Phase 3: ADVISE
+  Add NSHealthShareUsageDescription: "View your daily step count and activity trends"
+  Create separate entitlements files for staging and production
+  Implement progressive location permission: when-in-use first, then always with explanation
+  Generate PrivacyInfo.xcprivacy with required reason API declarations
+
+Phase 4: VALIDATE
+  All permission descriptions present after fix: YES
+  Entitlements clean for production: YES (after staging URL removal)
+  Privacy manifest complete: YES (after generation)
+  Store submission ready: PASS
+```
+
+## Gates
+
+- **No missing permission usage descriptions.** Every permission requested in code must have a corresponding usage description in the platform manifest. Missing descriptions cause automatic App Store rejection on iOS and are a best practice requirement on Android.
+- **No deep links to authenticated content without auth checks.** Every deep link handler that navigates to a protected screen must verify authentication state first. Unauthenticated users must be redirected to login with the deep link preserved for post-login navigation.
+- **No publishing with staging configuration.** Staging URLs, debug API keys, or test server endpoints in production build configurations are always an error. Verify build variants isolate environment-specific values.
+- **No requesting all permissions at app launch.** Permissions must be requested at the point of use with contextual explanation. Requesting all permissions on first launch results in lower grant rates and potential store rejection.
+
+## Escalation
+
+- **When platform-specific native code is required but the team uses a cross-platform framework:** Flag the bridging need: "This feature requires a custom native module for iOS (Swift) and Android (Kotlin). The React Native bridge needs to be implemented in `ios/` and `android/` directories. Consider if an existing library covers this use case."
+- **When app store guidelines have recently changed:** If the analysis references a guideline that may be outdated, flag it: "Apple updated App Review Guidelines in [month]. The privacy manifest requirements may have changed -- verify against the current guidelines at developer.apple.com."
+- **When deep linking requires server-side configuration:** If universal links or app links need server-side files, flag the cross-team dependency: "Universal Links require hosting `.well-known/apple-app-site-association` on your web domain. This needs coordination with the web/infrastructure team."
+- **When push notification testing requires physical devices:** Flag the testing limitation: "Push notification delivery cannot be fully tested in simulators. APNs requires a physical device with a valid push token. Consider using a staging environment with real devices for end-to-end push testing."

package/dist/agents/skills/gemini-cli/harness-mobile-patterns/skill.yaml

@@ -0,0 +1,82 @@
+name: harness-mobile-patterns
+version: "1.0.0"
+description: Mobile platform lifecycle, permissions, deep linking, push notifications, and app store submission
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_new_feature
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-mobile-patterns
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: platform
+      description: "Target platform: ios, android, react-native, flutter. Auto-detected when omitted."
+      required: false
+    - name: focus
+      description: "Audit focus: permissions, deep-links, push, lifecycle, store-submission, all. Defaults to all."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-mobile-patterns
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - mobile
+  - iOS
+  - Android
+  - React Native
+  - Flutter
+  - Swift
+  - Kotlin
+  - permissions
+  - deep link
+  - push notification
+  - app store
+  - Play Store
+  - App Store
+  - lifecycle
+  - universal link
+stack_signals:
+  - "ios/"
+  - "android/"
+  - "App.tsx"
+  - "app.json"
+  - "pubspec.yaml"
+  - "Info.plist"
+  - "AndroidManifest.xml"
+  - "*.xcodeproj"
+  - "*.gradle"
+phases:
+  - name: detect
+    description: Identify mobile platform, framework, native modules, and platform-specific configurations
+    required: true
+  - name: analyze
+    description: Evaluate permission handling, lifecycle management, deep linking, and push notification setup
+    required: true
+  - name: advise
+    description: Recommend platform-specific best practices, missing configurations, and store compliance fixes
+    required: true
+  - name: validate
+    description: Verify configurations are complete, permissions are justified, and store guidelines are met
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/harness-mutation-test/SKILL.md

@@ -0,0 +1,251 @@
+# Harness Mutation Test
+
+> Test quality validation through mutation testing. Introduces deliberate code mutations to verify that the test suite catches real bugs, exposing weak assertions, missing edge cases, and dead test code.
+
+## When to Use
+
+- Evaluating test suite quality after reaching a coverage threshold (e.g., 80% line coverage)
+- Validating that tests for critical business logic actually catch bugs, not just execute code
+- Identifying which parts of the codebase have weak or superficial test coverage
+- NOT when test coverage is below 60% (write more tests first with harness-tdd)
+- NOT when optimizing test execution speed (mutation testing is inherently slow)
+- NOT when the codebase has no existing tests (establish a test foundation first)
+
+## Process
+
+### Phase 1: CONFIGURE -- Set Up Mutation Testing Framework
+
+1. **Detect the project's language and test framework.** Mutation testing tools are language-specific:
+   - **TypeScript/JavaScript:** Stryker Mutator with Vitest, Jest, or Mocha runner
+   - **Python:** mutmut or cosmic-ray with pytest
+   - **Java/Kotlin:** PIT (pitest) with JUnit or TestNG
+   - **C#:** Stryker.NET with NUnit, xUnit, or MSTest
+   - **Rust:** cargo-mutants
+
+2. **Install and configure the mutation framework.** Generate the configuration file:
+   - Target source directories (exclude generated code, vendor, node_modules)
+   - Test command and timeout multiplier (mutations may cause infinite loops)
+   - Mutant operators to enable (arithmetic, conditional, string, logical)
+   - Reporters (HTML for local review, JSON for CI integration)
+
+3. **Define the scope.** Mutation testing is expensive. Scope it:
+   - **Targeted run:** specific files or directories with high business value
+   - **Incremental run:** only files changed since the last mutation run
+   - **Full run:** entire codebase (reserve for milestones or nightly CI)
+
+4. **Set the mutation score threshold.** Define the minimum acceptable score:
+   - 80% for business-critical modules (payment, auth, data processing)
+   - 60% for general application code
+   - No threshold for infrastructure/glue code (routers, middleware wiring)
+
+5. **Verify the test suite passes before mutating.** Run the full test suite. All tests must pass. Mutation testing against a failing suite produces meaningless results.
+
+### Phase 2: GENERATE -- Create Mutants
+
+1. **Run mutant generation in dry-run mode.** List the mutations that will be applied without executing tests. Review:
+   - Total mutant count (hundreds to thousands depending on codebase size)
+   - Mutant distribution across files
+   - Types of mutations generated (arithmetic, conditional boundary, return value, etc.)
+
+2. **Review the mutant operators.** Ensure the configured operators are relevant:
+   - **Arithmetic:** `+` to `-`, `*` to `/` -- tests mathematical correctness
+   - **Conditional boundary:** `<` to `<=`, `>` to `>=` -- tests off-by-one handling
+   - **Negate conditional:** `==` to `!=`, `true` to `false` -- tests branch coverage
+   - **Return value:** return empty string, zero, null, empty array -- tests output validation
+   - **String mutation:** `"hello"` to `""` -- tests string handling
+   - **Remove call:** delete a method call entirely -- tests that side effects are verified
+
+3. **Estimate execution time.** Calculate:
+   - Number of mutants times average test suite duration divided by parallelism factor
+   - If estimated time exceeds 30 minutes, reduce scope or increase parallelism
+
+4. **Filter out equivalent mutants (where possible).** Some mutations produce functionally identical code (e.g., changing the order of commutative operations). Configure the framework to skip known equivalent patterns to reduce noise.
+
+### Phase 3: EXECUTE -- Run Tests Against Mutants
+
+1. **Execute the mutation test run.** Start the framework with the configured scope:
+
+   ```
+   npx stryker run --concurrency 4
+   ```
+
+   or
+
+   ```
+   pitest:mutationCoverage
+   ```
+
+2. **Monitor progress.** Track:
+   - Mutants tested vs. total
+   - Kill rate as it progresses
+   - Timeouts (mutants that cause infinite loops -- these count as killed)
+   - Errors (mutants that cause compilation failures -- these are stillborn, not counted)
+
+3. **Handle long-running mutations.** If a single mutant takes longer than 3x the normal test timeout:
+   - The mutation likely introduced an infinite loop
+   - The framework should kill it automatically (timeout = killed)
+   - If the framework hangs, check the timeout multiplier configuration
+
+4. **Collect results.** After completion, the framework produces:
+   - Mutation score: (killed + timeout) / (total - stillborn - ignored)
+   - Per-file mutation scores
+   - List of survived mutants with their locations and mutation descriptions
+
+### Phase 4: ANALYZE -- Interpret Results and Improve Tests
+
+1. **Review the overall mutation score.** Compare against the threshold:
+   - Above threshold: test quality is acceptable. Review survived mutants for targeted improvements.
+   - Below threshold: significant test gaps exist. Prioritize fixes by file criticality.
+
+2. **Examine survived mutants.** For each survived mutant, determine why the test suite did not catch it:
+   - **Missing assertion:** the test executes the code but does not assert on the affected output. Fix: add a specific assertion.
+   - **Missing test case:** no test covers the mutated branch. Fix: write a new test for that path.
+   - **Weak assertion:** the test asserts but too loosely (e.g., `toBeTruthy()` instead of `toBe(42)`). Fix: strengthen the assertion.
+   - **Equivalent mutant:** the mutation does not change observable behavior. Mark as ignored.
+
+3. **Prioritize improvements by business impact.** Focus on survived mutants in:
+   - Authentication and authorization logic
+   - Payment and billing calculations
+   - Data validation and sanitization
+   - Core domain algorithms
+
+4. **Write targeted tests for the highest-priority survived mutants.** For each:
+   - Write a test that fails against the mutated code but passes against the original
+   - Verify the test is meaningful (not just mutation-hunting -- it should test real behavior)
+   - Run the mutation test again on the affected file to confirm the mutant is now killed
+
+5. **Generate an improvement report.** Summarize:
+   - Starting mutation score vs. ending mutation score
+   - Number of survived mutants addressed
+   - Tests added or strengthened
+   - Remaining gaps with recommendations
+
+6. **Run `harness validate`.** Confirm the project passes all harness checks after test improvements.
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+## Harness Integration
+
+- **`harness validate`** -- Run in ANALYZE phase after tests are improved. Confirms project health with strengthened tests.
+- **`harness check-deps`** -- Run after CONFIGURE phase to verify mutation testing framework is in devDependencies.
+- **`emit_interaction`** -- Used to present mutation score results and survived mutant analysis to the human for prioritization decisions.
+- **Grep** -- Used in ANALYZE phase to find weak assertions (`toBeTruthy`, `toBeDefined`, `!= null`) and missing assertion patterns.
+- **Glob** -- Used to identify test files corresponding to source files with survived mutants.
+
+## Success Criteria
+
+- Mutation score meets or exceeds the defined threshold for targeted modules
+- Every survived mutant in critical business logic has been addressed or explicitly justified
+- New tests written for survived mutants test real behavior, not just mutation-specific code paths
+- Weak assertions (`toBeTruthy`, `toBeDefined`, `expect(result)` without matcher) are replaced with specific assertions
+- The mutation test configuration is committed and can run in CI
+- `harness validate` passes after test improvements
+
+## Examples
+
+### Example: Stryker Mutation Testing for a TypeScript Billing Module
+
+**CONFIGURE -- Stryker configuration:**
+
+```javascript
+// stryker.config.mjs
+/** @type {import('@stryker-mutator/api/core').PartialStrykerOptions} */
+export default {
+  mutate: ['src/billing/**/*.ts', '!src/billing/**/*.test.ts'],
+  testRunner: 'vitest',
+  reporters: ['html', 'clear-text', 'progress'],
+  coverageAnalysis: 'perTest',
+  timeoutMS: 30000,
+  concurrency: 4,
+  thresholds: {
+    high: 90,
+    low: 80,
+    break: 75,
+  },
+};
+```
+
+**ANALYZE -- Survived mutant investigation:**
+
+```
+Mutant #47: src/billing/calculate-discount.ts:23
+  Original:  if (quantity >= 10) { discount = 0.15; }
+  Mutation:   if (quantity > 10)  { discount = 0.15; }
+  Status:    SURVIVED
+
+Analysis: No test checks the boundary condition where quantity is exactly 10.
+The existing test uses quantity=20 (well above threshold) and quantity=5 (below).
+```
+
+**Fix -- Add boundary test:**
+
+```typescript
+// src/billing/calculate-discount.test.ts
+it('applies 15% discount when quantity is exactly 10', () => {
+  const result = calculateDiscount({ quantity: 10, unitPrice: 100 });
+  expect(result.discount).toBe(0.15);
+  expect(result.total).toBe(850);
+});
+
+it('does not apply discount when quantity is 9', () => {
+  const result = calculateDiscount({ quantity: 9, unitPrice: 100 });
+  expect(result.discount).toBe(0);
+  expect(result.total).toBe(900);
+});
+```
+
+### Example: PIT Mutation Testing for a Java Service
+
+**CONFIGURE -- Maven PIT plugin:**
+
+```xml
+<!-- pom.xml -->
+<plugin>
+  <groupId>org.pitest</groupId>
+  <artifactId>pitest-maven</artifactId>
+  <version>1.15.3</version>
+  <configuration>
+    <targetClasses>
+      <param>com.example.orders.*</param>
+    </targetClasses>
+    <targetTests>
+      <param>com.example.orders.*Test</param>
+    </targetTests>
+    <mutators>
+      <mutator>CONDITIONALS_BOUNDARY</mutator>
+      <mutator>NEGATE_CONDITIONALS</mutator>
+      <mutator>RETURN_VALS</mutator>
+      <mutator>MATH</mutator>
+    </mutators>
+    <mutationThreshold>80</mutationThreshold>
+    <timestampedReports>false</timestampedReports>
+  </configuration>
+</plugin>
+```
+
+**EXECUTE:**
+
+```bash
+mvn org.pitest:pitest-maven:mutationCoverage
+# Report generated at target/pit-reports/index.html
+```
+
+## Gates
+
+- **No mutation testing against a failing test suite.** All tests must pass before mutants are generated. Running mutations against broken tests produces garbage results. Fix the tests first.
+- **Survived mutants in critical modules must be addressed.** If a survived mutant is in authentication, billing, or data validation logic, it cannot be ignored. Write a test or justify why the mutation is equivalent.
+- **No gaming the mutation score.** Writing tests that only target survived mutants without testing real behavior inflates the score without improving quality. Every new test must test a meaningful behavior, not just kill a specific mutant.
+- **Mutation score regression blocks merge.** If the mutation score drops below the configured threshold after a code change, the change must include tests that restore the score before merging.
+
+## Escalation
+
+- **When mutation testing takes too long (> 1 hour for targeted run):** Reduce scope to changed files only. Use incremental mutation testing if the framework supports it. For full runs, schedule as a nightly CI job rather than blocking PRs.
+- **When a high number of equivalent mutants skew the score:** Review mutant operators. Disable operators that produce mostly equivalent mutants for the codebase (e.g., string mutations in a codebase with few string operations). Document disabled operators and the rationale.
+- **When the team disputes whether a survived mutant matters:** Evaluate: would a real bug in that code path cause user-visible harm? If yes, write the test. If no, document it as an accepted risk with a code comment explaining why.
+- **When mutation testing reveals architectural issues (untestable code):** This is a design signal, not a testing problem. Escalate to refactoring -- the code needs dependency injection, interface extraction, or seam creation before meaningful tests can be written.