feat(scanner): add verification scanner, settings, widget, sidebar, frontend display (v0.4.0)

includes/admin/class-pr-core-admin.php

@@ -4,16 +4,15 @@ declare(strict_types=1);
 /**
  * Admin initialization and hook registration.
  *
- * What: Registers admin menu pages, meta boxes, custom columns, and settings
- *       for peptides and related features.
+ * What: Registers admin menu pages, meta boxes, and custom columns for peptides.
  * Who calls it: PR_Core::init() when is_admin().
- * Dependencies: PR_Core_Peptide_Metaboxes, PR_Core_Candidate_Queue_Page,
- *               PR_Core_Admin_Columns, PR_Core_Settings.
+ * Dependencies: PR_Core_Peptide_Metaboxes, PR_Core_Verification_Metabox,
+ *               PR_Core_Candidate_Queue_Page, PR_Core_Admin_Columns.
  *
  * @see admin/class-pr-core-peptide-metaboxes.php    — Dosing + legal meta boxes.
+ * @see admin/class-pr-core-verification-metabox.php — Verification sidebar meta box.
  * @see admin/class-pr-core-candidate-queue-page.php — Candidate review screen.
  * @see admin/class-pr-core-admin-columns.php        — Custom list-table columns.
- * @see admin/class-pr-core-settings.php             — Plugin settings page.
  */
 class PR_Core_Admin {
 
@@ -29,13 +28,12 @@ class PR_Core_Admin {
 		add_action( 'add_meta_boxes', [ $metaboxes, 'add_meta_boxes' ] );
 		add_action( 'save_post_' . PR_Core_Peptide_CPT::POST_TYPE, [ $metaboxes, 'save_meta' ], 10, 2 );
 
+		add_action( 'add_meta_boxes', [ PR_Core_Verification_Metabox::class, 'register' ] );
+
 		$columns = new PR_Core_Admin_Columns();
 		add_filter( 'manage_' . PR_Core_Peptide_CPT::POST_TYPE . '_posts_columns', [ $columns, 'add_columns' ] );
 		add_action( 'manage_' . PR_Core_Peptide_CPT::POST_TYPE . '_posts_custom_column', [ $columns, 'render_column' ], 10, 2 );
 
-		$settings = new PR_Core_Settings();
-		$settings->register_hooks();
-
 		add_action( 'admin_menu', [ $this, 'add_admin_pages' ] );
 		add_action( 'admin_enqueue_scripts', [ $this, 'enqueue_admin_styles' ] );
 	}

includes/admin/class-pr-core-ajax-handlers.php

@@ -0,0 +1,79 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * AJAX handlers for verification scanner actions.
+ *
+ * What: Handles mark-verified and scan-now admin-ajax actions.
+ * Who calls it: PR_Core::init() registers the wp_ajax hooks.
+ * Dependencies: None.
+ *
+ * @see admin/class-pr-core-peptide-metaboxes.php — "Mark verified today" button in sidebar.
+ * @see admin/class-pr-core-verification-widget.php — "Scan now" button in dashboard widget.
+ */
+class PR_Core_Ajax_Handlers {
+
+	/**
+	 * Handle mark-verified AJAX action.
+	 *
+	 * Updates _pr_last_source_verified to today, saves notes, recomputes status.
+	 *
+	 * Side effects: Updates post meta, returns JSON.
+	 *
+	 * @return void
+	 */
+	public static function handle_mark_verified(): void {
+		// Verify nonce.
+		$nonce = sanitize_text_field( wp_unslash( $_POST['nonce'] ?? '' ) );
+		if ( ! wp_verify_nonce( $nonce, 'wp_nonce' ) ) {
+			wp_send_json_error( 'Invalid nonce' );
+		}
+
+		// Get post ID and verify capability.
+		$post_id = absint( wp_unslash( $_POST['post_id'] ?? 0 ) );
+		if ( ! $post_id || ! current_user_can( PR_Core_Peptide_CPT::CAPABILITY ) ) {
+			wp_send_json_error( 'Unauthorized' );
+		}
+
+		// Update verified date.
+		update_post_meta( $post_id, '_pr_last_source_verified', current_time( 'mysql' ) );
+
+		// Save notes if provided.
+		$notes = sanitize_textarea_field( wp_unslash( $_POST['notes'] ?? '' ) );
+		if ( $notes ) {
+			update_post_meta( $post_id, '_pr_verification_notes', $notes );
+		}
+
+		// Recompute status to 'current'.
+		update_post_meta( $post_id, '_pr_verification_status', 'current' );
+
+		wp_send_json_success( [ 'message' => 'Marked verified' ] );
+	}
+
+	/**
+	 * Handle scan-now AJAX action.
+	 *
+	 * Runs verification scanner immediately.
+	 *
+	 * Side effects: Runs scan, returns JSON.
+	 *
+	 * @return void
+	 */
+	public static function handle_scan_now(): void {
+		// Verify nonce.
+		$nonce = sanitize_text_field( wp_unslash( $_POST['nonce'] ?? '' ) );
+		if ( ! wp_verify_nonce( $nonce, 'pr_core_scan_now' ) ) {
+			wp_send_json_error( 'Invalid nonce' );
+		}
+
+		// Verify capability.
+		if ( ! current_user_can( 'manage_options' ) ) {
+			wp_send_json_error( 'Unauthorized' );
+		}
+
+		// Run scan.
+		PR_Core_Verification_Scanner::run_scan();
+
+		wp_send_json_success( [ 'message' => 'Scan complete' ] );
+	}
+}

includes/admin/class-pr-core-settings.php

@@ -2,110 +2,69 @@
 declare(strict_types=1);
 
 /**
- * Settings page for PR Core plugin features.
+ * Settings page for PR Core plugin configuration.
  *
- * What: Registers admin menu, renders settings form, and handles option saves
- *       for features like Related Articles.
- * Who calls it: PR_Core_Admin::register_hooks().
- * Dependencies: None (reads/writes wp_options).
+ * What: Static admin settings class. Registers and renders the PR Core settings
+ *       page under Peptides, with sections for Related Articles and Verification.
+ * Who calls it: PR_Core::init() via admin_menu and admin_init hooks.
+ * Dependencies: PR_Core_Peptide_CPT (for CAPABILITY constant).
+ *
+ * @see class-pr-core.php — Registers admin_menu + admin_init hooks pointing here.
  */
 class PR_Core_Settings {
 
+	/** @var string Option group shared by all PR Core settings. */
+	public const OPTION_GROUP = 'pr_core_settings';
+
 	/** @var string Option key: enable/disable related articles. */
-	private const ENABLED_OPTION = 'pr_core_related_posts_enabled';
+	private const RELATED_ENABLED = 'pr_core_related_posts_enabled';
 
 	/** @var string Option key: related articles limit (1-6). */
-	private const LIMIT_OPTION = 'pr_core_related_posts_limit';
+	private const RELATED_LIMIT = 'pr_core_related_posts_limit';
+
+	/** @var string Option key: WP-cron scan cadence. */
+	private const SCAN_CADENCE = 'pr_core_scan_cadence';
+
+	/** @var string Option key: default staleness threshold in days. */
+	private const DEFAULT_THRESHOLD = 'pr_core_default_threshold';
+
+	/** @var string Option key: high-velocity staleness threshold in days. */
+	private const HIGH_VELOCITY_THRESHOLD = 'pr_core_high_velocity_threshold';
+
+	/** @var string Option key: comma-separated notification email list. */
+	private const VERIFICATION_EMAIL = 'pr_core_verification_email';
 
 	/**
-	 * Register admin page and settings hooks.
+	 * Register the settings submenu page under Peptides.
+	 *
+	 * Side effects: calls add_submenu_page().
 	 *
 	 * @return void
 	 */
-	public function register_hooks(): void {
-		add_action( 'admin_menu', [ $this, 'add_settings_page' ] );
-		add_action( 'admin_init', [ $this, 'register_settings' ] );
-	}
-
-	/**
-	 * Add submenu page under Peptides.
-	 *
-	 * @return void
-	 */
-	public function add_settings_page(): void {
+	public static function add_settings_page(): void {
 		add_submenu_page(
 			'edit.php?post_type=' . PR_Core_Peptide_CPT::POST_TYPE,
 			__( 'PR Core Settings', 'peptide-repo-core' ),
 			__( 'Settings', 'peptide-repo-core' ),
 			'manage_options',
 			'pr-core-settings',
-			[ $this, 'render_page' ]
+			[ __CLASS__, 'render_page' ]
 		);
 	}
 
 	/**
-	 * Register settings fields.
+	 * Render the settings page form.
 	 *
 	 * @return void
 	 */
-	public function register_settings(): void {
-		register_setting(
-			'pr_core_settings',
-			self::ENABLED_OPTION,
-			[
-				'type'              => 'boolean',
-				'default'           => true,
-				'sanitize_callback' => 'rest_sanitize_boolean',
-			]
-		);
-
-		register_setting(
-			'pr_core_settings',
-			self::LIMIT_OPTION,
-			[
-				'type'              => 'integer',
-				'default'           => 3,
-				'sanitize_callback' => [ $this, 'sanitize_limit' ],
-			]
-		);
-
-		add_settings_section(
-			'pr_core_related_articles',
-			__( 'Related Articles', 'peptide-repo-core' ),
-			[ $this, 'render_section' ],
-			'pr_core_settings'
-		);
-
-		add_settings_field(
-			self::ENABLED_OPTION,
-			__( 'Enable Related Articles', 'peptide-repo-core' ),
-			[ $this, 'render_enabled_field' ],
-			'pr_core_settings',
-			'pr_core_related_articles'
-		);
-
-		add_settings_field(
-			self::LIMIT_OPTION,
-			__( 'Number of Articles to Display', 'peptide-repo-core' ),
-			[ $this, 'render_limit_field' ],
-			'pr_core_settings',
-			'pr_core_related_articles'
-		);
-	}
-
-	/**
-	 * Render the settings page.
-	 *
-	 * @return void
-	 */
-	public function render_page(): void {
+	public static function render_page(): void {
 		?>
 		<div class="wrap">
-			<h1><?php esc_html_e( 'Peptide Repo Core Settings', 'peptide-repo-core' ); ?></h1>
+			<h1><?php esc_html_e( 'PR Core Settings', 'peptide-repo-core' ); ?></h1>
 			<form method="post" action="options.php">
 				<?php
-				settings_fields( 'pr_core_settings' );
-				do_settings_sections( 'pr_core_settings' );
+				settings_fields( self::OPTION_GROUP );
+				do_settings_sections( self::OPTION_GROUP );
 				submit_button();
 				?>
 			</form>
@@ -114,63 +73,159 @@ class PR_Core_Settings {
 	}
 
 	/**
-	 * Render section description.
+	 * Register all settings, sections, and fields on admin_init.
+	 *
+	 * Side effects: calls register_setting(), add_settings_section(),
+	 *               add_settings_field(), add_action() for cron reschedule.
 	 *
 	 * @return void
 	 */
-	public function render_section(): void {
-		echo '<p>' . esc_html__( 'Configure the Related Articles section that appears on peptide single pages.', 'peptide-repo-core' ) . '</p>';
+	public static function register_settings(): void {
+		self::register_related_articles_section();
+		self::register_verification_section();
+		add_action( 'update_option_' . self::SCAN_CADENCE, [ __CLASS__, 'reschedule_cron' ], 10, 2 );
 	}
 
+	// ── Related Articles ─────────────────────────────────────────────────
+
 	/**
-	 * Render enabled toggle field.
+	 * Register Related Articles settings.
 	 *
 	 * @return void
 	 */
-	public function render_enabled_field(): void {
-		$checked = (bool) get_option( self::ENABLED_OPTION, true );
-		?>
-		<input
-			type="checkbox"
-			name="<?php echo esc_attr( self::ENABLED_OPTION ); ?>"
-			value="1"
-			<?php checked( $checked, true ); ?>
-		/>
-		<label>
-			<?php esc_html_e( 'Display related articles on peptide pages', 'peptide-repo-core' ); ?>
-		</label>
-		<?php
+	private static function register_related_articles_section(): void {
+		register_setting( self::OPTION_GROUP, self::RELATED_ENABLED, [ 'type' => 'boolean', 'default' => true,    'sanitize_callback' => 'rest_sanitize_boolean' ] );
+		register_setting( self::OPTION_GROUP, self::RELATED_LIMIT,   [ 'type' => 'integer', 'default' => 3,       'sanitize_callback' => [ __CLASS__, 'sanitize_limit' ] ] );
+
+		add_settings_section( 'pr_core_related_articles', __( 'Related Articles', 'peptide-repo-core' ), '__return_false', self::OPTION_GROUP );
+		add_settings_field( self::RELATED_ENABLED, __( 'Enable Related Articles', 'peptide-repo-core' ), [ __CLASS__, 'render_enabled_field' ], self::OPTION_GROUP, 'pr_core_related_articles' );
+		add_settings_field( self::RELATED_LIMIT,   __( 'Number of Articles',      'peptide-repo-core' ), [ __CLASS__, 'render_limit_field'   ], self::OPTION_GROUP, 'pr_core_related_articles' );
+	}
+
+	/** @return void */
+	public static function render_enabled_field(): void {
+		$enabled = (bool) get_option( self::RELATED_ENABLED, true );
+		printf(
+			'<input type="checkbox" name="%s" value="1"%s /> %s',
+			esc_attr( self::RELATED_ENABLED ),
+			checked( $enabled, true, false ),
+			esc_html__( 'Show related monographs on single peptide pages', 'peptide-repo-core' )
+		);
+	}
+
+	/** @return void */
+	public static function render_limit_field(): void {
+		printf(
+			'<input type="number" name="%s" value="%d" min="1" max="6" />',
+			esc_attr( self::RELATED_LIMIT ),
+			absint( get_option( self::RELATED_LIMIT, 3 ) )
+		);
+		echo '<p class="description">' . esc_html__( 'Number of articles to display (1-6). Default: 3.', 'peptide-repo-core' ) . '</p>';
 	}
 
 	/**
-	 * Render limit field.
-	 *
-	 * @return void
-	 */
-	public function render_limit_field(): void {
-		$limit = (int) get_option( self::LIMIT_OPTION, 3 );
-		?>
-		<input
-			type="number"
-			name="<?php echo esc_attr( self::LIMIT_OPTION ); ?>"
-			value="<?php echo esc_attr( (string) $limit ); ?>"
-			min="1"
-			max="6"
-		/>
-		<p class="description">
-			<?php esc_html_e( 'Number of articles to display (1-6). Default: 3.', 'peptide-repo-core' ); ?>
-		</p>
-		<?php
-	}
-
-	/**
-	 * Sanitize limit to 1-6 range.
+	 * Sanitize the related articles limit to 1-6.
 	 *
 	 * @param mixed $value Raw input.
-	 * @return int Sanitized value.
+	 * @return int
 	 */
-	public function sanitize_limit( $value ): int {
-		$limit = (int) $value;
-		return min( 6, max( 1, $limit ) );
+	public static function sanitize_limit( $value ): int {
+		return min( 6, max( 1, (int) $value ) );
+	}
+
+	// ── Verification ─────────────────────────────────────────────────────
+
+	/**
+	 * Register Verification settings.
+	 *
+	 * @return void
+	 */
+	private static function register_verification_section(): void {
+		register_setting( self::OPTION_GROUP, self::SCAN_CADENCE,            [ 'type' => 'string',  'default' => 'weekly', 'sanitize_callback' => [ __CLASS__, 'sanitize_cadence' ] ] );
+		register_setting( self::OPTION_GROUP, self::DEFAULT_THRESHOLD,       [ 'type' => 'integer', 'default' => 180,      'sanitize_callback' => 'absint' ] );
+		register_setting( self::OPTION_GROUP, self::HIGH_VELOCITY_THRESHOLD, [ 'type' => 'integer', 'default' => 60,       'sanitize_callback' => 'absint' ] );
+		register_setting( self::OPTION_GROUP, self::VERIFICATION_EMAIL,      [ 'type' => 'string',  'default' => '',       'sanitize_callback' => [ __CLASS__, 'sanitize_emails' ] ] );
+
+		add_settings_section( 'pr_core_verification', __( 'Verification', 'peptide-repo-core' ), [ __CLASS__, 'render_verification_section' ], self::OPTION_GROUP );
+		add_settings_field( self::SCAN_CADENCE,            __( 'Scan cadence',                       'peptide-repo-core' ), [ __CLASS__, 'render_cadence_field'       ], self::OPTION_GROUP, 'pr_core_verification' );
+		add_settings_field( self::DEFAULT_THRESHOLD,       __( 'Default staleness threshold (days)',  'peptide-repo-core' ), [ __CLASS__, 'render_threshold_field'     ], self::OPTION_GROUP, 'pr_core_verification' );
+		add_settings_field( self::HIGH_VELOCITY_THRESHOLD, __( 'High-velocity threshold (days)',      'peptide-repo-core' ), [ __CLASS__, 'render_high_velocity_field' ], self::OPTION_GROUP, 'pr_core_verification' );
+		add_settings_field( self::VERIFICATION_EMAIL,      __( 'Notification email(s)',               'peptide-repo-core' ), [ __CLASS__, 'render_email_field'         ], self::OPTION_GROUP, 'pr_core_verification' );
+	}
+
+	/** @return void */
+	public static function render_verification_section(): void {
+		echo '<p>' . esc_html__( 'Configure automatic staleness scanning and digest notifications.', 'peptide-repo-core' ) . '</p>';
+	}
+
+	/** @return void */
+	public static function render_cadence_field(): void {
+		$current = get_option( self::SCAN_CADENCE, 'weekly' );
+		echo '<select name="' . esc_attr( self::SCAN_CADENCE ) . '">';
+		foreach ( [ 'daily' => 'Daily', 'weekly' => 'Weekly', 'monthly' => 'Monthly' ] as $val => $label ) {
+			printf( '<option value="%s"%s>%s</option>', esc_attr( $val ), selected( $current, $val, false ), esc_html( $label ) );
+		}
+		echo '</select>';
+	}
+
+	/** @return void */
+	public static function render_threshold_field(): void {
+		printf( '<input type="number" name="%s" value="%d" min="1" />', esc_attr( self::DEFAULT_THRESHOLD ), absint( get_option( self::DEFAULT_THRESHOLD, 180 ) ) );
+	}
+
+	/** @return void */
+	public static function render_high_velocity_field(): void {
+		printf( '<input type="number" name="%s" value="%d" min="1" />', esc_attr( self::HIGH_VELOCITY_THRESHOLD ), absint( get_option( self::HIGH_VELOCITY_THRESHOLD, 60 ) ) );
+	}
+
+	/** @return void */
+	public static function render_email_field(): void {
+		printf(
+			'<input type="text" name="%s" value="%s" class="regular-text" placeholder="admin@example.com" />',
+			esc_attr( self::VERIFICATION_EMAIL ),
+			esc_attr( (string) get_option( self::VERIFICATION_EMAIL, '' ) )
+		);
+		echo '<p class="description">' . esc_html__( 'Comma-separated. Leave blank to disable email digests.', 'peptide-repo-core' ) . '</p>';
+	}
+
+	/**
+	 * Sanitize cadence to allowed WP-cron recurrence values.
+	 *
+	 * @param string $value Raw input.
+	 * @return string
+	 */
+	public static function sanitize_cadence( string $value ): string {
+		return in_array( $value, [ 'daily', 'weekly', 'monthly' ], true ) ? $value : 'weekly';
+	}
+
+	/**
+	 * Sanitize comma-separated email list, keeping only valid addresses.
+	 *
+	 * @param string $value Raw input.
+	 * @return string
+	 */
+	public static function sanitize_emails( string $value ): string {
+		if ( '' === $value ) {
+			return '';
+		}
+		$valid = array_filter( array_map( 'trim', explode( ',', $value ) ), 'is_email' );
+		return implode( ', ', $valid );
+	}
+
+	/**
+	 * Reschedule the verification cron when cadence changes.
+	 *
+	 * Fires on: update_option_pr_core_scan_cadence.
+	 *
+	 * @param mixed $old_value Previous option value.
+	 * @param mixed $new_value New option value.
+	 * @return void
+	 */
+	public static function reschedule_cron( $old_value, $new_value ): void {
+		if ( $old_value === $new_value ) {
+			return;
+		}
+		wp_clear_scheduled_hook( 'pr_core_verification_scan' );
+		wp_schedule_event( time(), (string) $new_value, 'pr_core_verification_scan' );
 	}
 }

includes/admin/class-pr-core-verification-metabox.php

@@ -0,0 +1,91 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Verification status meta box for peptide edit screen.
+ *
+ * What: Renders and saves verification status sidebar meta box.
+ * Who calls it: PR_Core_Admin via add_meta_boxes and save_post hooks.
+ * Dependencies: None.
+ *
+ * @see admin/class-pr-core-peptide-metaboxes.php — Other edit-screen meta boxes.
+ */
+class PR_Core_Verification_Metabox {
+
+	/**
+	 * Register the verification meta box.
+	 *
+	 * @return void
+	 */
+	public static function register(): void {
+		add_meta_box(
+			'pr-core-verification',
+			__( 'Verification Status', 'peptide-repo-core' ),
+			[ __CLASS__, 'render' ],
+			PR_Core_Peptide_CPT::POST_TYPE,
+			'side',
+			'default'
+		);
+	}
+
+	/**
+	 * Render the verification status meta box (sidebar).
+	 *
+	 * @param \WP_Post $post Current post.
+	 * @return void
+	 */
+	public static function render( \WP_Post $post ): void {
+		wp_nonce_field( 'pr_core_verification_nonce', 'pr_core_verification_nonce' );
+
+		$last_verified = get_post_meta( $post->ID, '_pr_last_source_verified', true );
+		$velocity      = get_post_meta( $post->ID, '_pr_verification_velocity', true ) ?: 'medium';
+		$status        = get_post_meta( $post->ID, '_pr_verification_status', true ) ?: 'current';
+		$notes         = get_post_meta( $post->ID, '_pr_verification_notes', true ) ?: '';
+
+		echo '<p><strong>' . esc_html__( 'Last Verified', 'peptide-repo-core' ) . ':</strong><br />';
+		echo '<code style="color: #666;">' . esc_html( $last_verified ?: '—' ) . '</code></p>';
+
+		echo '<p><strong>' . esc_html__( 'Verification Velocity', 'peptide-repo-core' ) . ':</strong><br />';
+		echo '<select name="pr_core__pr_verification_velocity" style="width:100%;">';
+		foreach ( [ 'low' => 'Low', 'medium' => 'Medium', 'high' => 'High' ] as $val => $label ) {
+			printf(
+				'<option value="%s"%s>%s</option>',
+				esc_attr( $val ),
+				selected( $velocity, $val, false ),
+				esc_html( $label )
+			);
+		}
+		echo '</select></p>';
+
+		echo '<p><strong>' . esc_html__( 'Status', 'peptide-repo-core' ) . ':</strong><br />';
+		$badge_class = match( $status ) {
+			'due' => 'style="background:#ff9800;color:white;padding:4px 8px;border-radius:3px;"',
+			'overdue' => 'style="background:#f44336;color:white;padding:4px 8px;border-radius:3px;"',
+			default => 'style="background:#4caf50;color:white;padding:4px 8px;border-radius:3px;"',
+		};
+		echo '<span ' . $badge_class . '>' . esc_html( ucfirst( $status ) ) . '</span></p>';
+
+		echo '<p><strong>' . esc_html__( 'Verification Notes', 'peptide-repo-core' ) . ':</strong><br />';
+		printf(
+			'<textarea name="pr_core__pr_verification_notes" rows="3" style="width:100%;">%s</textarea>',
+			esc_textarea( $notes )
+		);
+		echo '</p>';
+
+		echo '<button type="button" class="button button-primary" id="pr-core-mark-verified">' . esc_html__( 'Mark Verified Today', 'peptide-repo-core' ) . '</button>';
+
+		echo '<script>
+		document.getElementById("pr-core-mark-verified").addEventListener("click", function() {
+			const data = new FormData();
+			data.append("action", "pr_core_mark_verified");
+			data.append("post_id", ' . (int) $post->ID . ');
+			data.append("nonce", document.querySelector("[name=\'_wpnonce\']").value);
+			data.append("notes", document.querySelector("[name=\'pr_core__pr_verification_notes\']").value);
+			fetch(ajaxurl, { method: "POST", body: data })
+				.then(r => r.json())
+				.then(d => { if(d.success) { location.reload(); } else { alert("Error: " + (d.data || "Unknown")); }})
+				.catch(e => { alert("Error: " + e); });
+		});
+		</script>';
+	}
+}

includes/admin/class-pr-core-verification-widget.php

@@ -0,0 +1,113 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Dashboard widget for verification status overview.
+ *
+ * What: WordPress dashboard widget showing peptides needing review (due/overdue).
+ * Who calls it: PR_Core::init() hooks wp_dashboard_setup.
+ * Dependencies: PR_Core_Peptide_Repository.
+ *
+ * @see scanner/class-pr-core-verification-scanner.php — Computes status via run_scan().
+ */
+class PR_Core_Verification_Widget {
+
+	/**
+	 * Register the dashboard widget.
+	 *
+	 * Side effects: Registers WP dashboard widget.
+	 *
+	 * @return void
+	 */
+	public static function register(): void {
+		wp_add_dashboard_widget(
+			'pr_core_verification_status',
+			__( 'Monographs Needing Review', 'peptide-repo-core' ),
+			[ __CLASS__, 'render' ]
+		);
+	}
+
+	/**
+	 * Render the widget content.
+	 *
+	 * @return void
+	 */
+	public static function render(): void {
+		$repo = new PR_Core_Peptide_Repository();
+		$peptides = $repo->find_all( [ 'status' => 'publish' ] );
+
+		$due_overdue = [];
+
+		foreach ( $peptides as $dto ) {
+			$status = get_post_meta( $dto->id, '_pr_verification_status', true ) ?: 'current';
+
+			if ( in_array( $status, [ 'due', 'overdue' ], true ) ) {
+				$last_verified = get_post_meta( $dto->id, '_pr_last_source_verified', true );
+				$days_since    = $last_verified
+					? (int) ( ( time() - strtotime( $last_verified ) ) / DAY_IN_SECONDS )
+					: 999;
+
+				$due_overdue[] = [
+					'id'           => $dto->id,
+					'title'        => $dto->title,
+					'status'       => $status,
+					'velocity'     => get_post_meta( $dto->id, '_pr_verification_velocity', true ) ?: 'medium',
+					'last_verified' => $last_verified,
+					'days_since'   => $days_since,
+				];
+			}
+		}
+
+		// Sort by days_since descending (most overdue first).
+		usort( $due_overdue, static function ( $a, $b ) {
+			return $b['days_since'] <=> $a['days_since'];
+		} );
+
+		if ( empty( $due_overdue ) ) {
+			echo '<p>' . esc_html__( 'All monographs are current. ', 'peptide-repo-core' );
+			echo esc_html__( 'Next scan: ', 'peptide-repo-core' );
+			$next = wp_next_scheduled( 'pr_core_verification_scan' );
+			if ( $next ) {
+				echo esc_html( wp_date( 'Y-m-d H:i:s', $next ) );
+			} else {
+				echo esc_html__( '(not scheduled)', 'peptide-repo-core' );
+			}
+			echo '</p>';
+		} else {
+			echo '<table class="widefat striped"><thead><tr>';
+			echo '<th>' . esc_html__( 'Title', 'peptide-repo-core' ) . '</th>';
+			echo '<th>' . esc_html__( 'Verdict', 'peptide-repo-core' ) . '</th>';
+			echo '<th>' . esc_html__( 'Velocity', 'peptide-repo-core' ) . '</th>';
+			echo '<th>' . esc_html__( 'Last Verified', 'peptide-repo-core' ) . '</th>';
+			echo '<th>' . esc_html__( 'Days Overdue', 'peptide-repo-core' ) . '</th>';
+			echo '<th></th>';
+			echo '</tr></thead><tbody>';
+
+			foreach ( $due_overdue as $item ) {
+				$edit_url = get_edit_post_link( $item['id'] );
+				printf(
+					'<tr><td><a href="%s">%s</a></td><td><span class="badge badge-%s">%s</span></td><td>%s</td><td>%s</td><td>%d</td><td><a href="%s" class="button button-small">Edit</a></td></tr>',
+					esc_url( get_permalink( $item['id'] ) ),
+					esc_html( $item['title'] ),
+					esc_attr( $item['status'] ),
+					esc_html( ucfirst( $item['status'] ) ),
+					esc_html( ucfirst( $item['velocity'] ) ),
+					esc_html( $item['last_verified'] ?? '—' ),
+					$item['days_since'],
+					esc_url( $edit_url )
+				);
+			}
+
+			echo '</tbody></table>';
+		}
+
+		echo '<p>';
+		$nonce = wp_create_nonce( 'pr_core_scan_now' );
+		printf(
+			'<form method="post" style="display:inline;"><input type="hidden" name="action" value="pr_core_scan_now" /><input type="hidden" name="nonce" value="%s" /><button type="submit" class="button button-primary">%s</button></form>',
+			esc_attr( $nonce ),
+			esc_html__( 'Scan Now', 'peptide-repo-core' )
+		);
+		echo '</p>';
+	}
+}