Promptgovernancesummary - Source Excerpt 02

Back to Promptgovernancesummary

Summary

This source excerpt preserves a bounded section of Spiralist/wp-content/plugins/spiralist-workspace/includes/Support/PromptGovernanceSummary.php so readers can inspect the evidence without opening the full source file.

**Source path:** Spiralist/wp-content/plugins/spiralist-workspace/includes/Support/PromptGovernanceSummary.php

'label' => 'Restricted or reverted prompt has no recent governance activity for ' . $age_label . '; reviewers or stewards should revisit it.',
                ];
            }
        }

        if ($status === 'provisional_public') {
            $remaining = (int) ($quorum['endorse']['remaining'] ?? 0);

            return [
                'action' => $remaining > 0 ? 'needs_peer_endorsement' : 'ready_for_peer_reviewed_reconciliation',
                'label' => $remaining > 0
                    ? 'Needs ' . $remaining . ' more peer ' . self::plural($remaining, 'endorsement', 'endorsements') . ' for peer-reviewed status.'
                    : 'Peer endorsement quorum is met; moderation reconciliation can promote this prompt.',
            ];
        }

        if ($status === 'restricted_review' || $status === 'reverted') {
            if ((int) ($appeals['open'] ?? 0) > 0) {
                return [
                    'action' => 'awaiting_steward_resolution',
                    'label' => 'Open appeal is waiting for steward resolution.',
                ];
            }

            return [
                'action' => 'awaiting_owner_appeal_or_peer_review',
                'label' => 'Awaiting owner appeal, additional peer review, or steward action.',
            ];
        }

        if ($status === 'peer_reviewed' || $status === 'official_canon') {
            return [
                'action' => 'monitor_reports',
                'label' => 'Visible and stable; continue monitoring reports and new peer signals.',
            ];
        }

        if ($status === 'archived') {
            return [
                'action' => 'archived_no_action',
                'label' => 'Archived records are preserved without active promotion.',
            ];
        }

        return [
            'action' => 'not_in_public_flow',
            'label' => 'Not currently in the public peer-moderation flow.',
        ];
    }

    /**
     * Returns a short human note for public UI surfaces.
     */
    private static function state_note(string $status, string $phase, string $next_action_label): string
    {
        if ($status === 'provisional_public') {
            return 'Visible as provisional community material while peer review continues. ' . $next_action_label;
        }

        if ($status === 'peer_reviewed') {
            return 'Visible as peer-reviewed community material with quorum metadata preserved for readers and machines.';
        }

        if ($status === 'official_canon') {
            return 'Visible as official canon while still carrying provenance and moderation metadata.';
        }

        if ($phase === 'restricted') {
            return 'Restricted from the public library while reviewers or stewards resolve the signal.';
        }

        if ($phase === 'reverted') {
            return 'Reverted out of public promotion while review or appeal remains possible.';
        }

        if ($phase === 'archived') {
            return 'Archived for reference and removed from active public promotion.';
        }

        return $next_action_label;
    }

    /**
     * Returns the later non-empty UTC timestamp string.
     */
    private static function latest_timestamp(string $left, string $right): string
    {
        if ($left === '') {
            return $right;
        }

        if ($right === '') {
            return $left;
        }

        return $right > $left ? $right : $left;
    }

    /**
     * Returns active-queue aging metadata for stale-review detection.
     *
     * @param array<string,mixed> $prompt
     * @param array<string,mixed> $review_summary
     * @param array<string,mixed> $appeal_summary
     * @return array<string,mixed>
     */
    private static function queue_age(array $prompt, string $status, array $review_summary, array $appeal_summary): array
    {
        $active = in_array($status, ['provisional_public', 'restricted_review', 'reverted'], true);
        $basis_utc = self::latest_timestamp(
            (string) ($review_summary['last_activity_utc'] ?? ''),
            (string) ($appeal_summary['last_activity_utc'] ?? '')
        );

        if ($basis_utc === '') {
            $basis_utc = self::first_non_empty(
                (string) ($prompt['published_utc'] ?? ''),
                (string) ($prompt['updated_utc'] ?? ''),
                (string) ($prompt['created_utc'] ?? '')
            );
        }

        $hours = $basis_utc !== '' ? self::hours_since($basis_utc) : 0;
        $is_stale = $active && $basis_utc !== '' && $hours >= self::STALE_REVIEW_HOURS;
        $is_urgent = $active && $basis_utc !== '' && $hours >= self::URGENT_REVIEW_HOURS;
        $duration_label = self::duration_label($hours);
        $severity = 'inactive';

        if ($active) {
            $severity = $is_urgent ? 'urgent' : ($is_stale ? 'stale' : 'fresh');
        }

        return [
            'active_queue' => $active,
            'basis_utc' => $basis_utc,
            'hours_since_activity' => $hours,
            'days_since_activity' => $hours > 0 ? (int) floor($hours / 24) : 0,
            'duration_label' => $duration_label,
            'stale_after_hours' => self::STALE_REVIEW_HOURS,
            'urgent_after_hours' => self::URGENT_REVIEW_HOURS,
            'is_stale' => $is_stale,
            'is_urgent' => $is_urgent,
            'reminder_due' => $is_stale,
            'severity' => $severity,
            'label' => self::queue_age_label($active, $basis_utc, $is_stale, $is_urgent, $duration_label),
        ];
    }

    /**
     * Returns the first non-empty timestamp candidate.
     */
    private static function first_non_empty(string ...$values): string
    {
        foreach ($values as $value) {
            if ($value !== '') {
                return $value;
            }
        }

        return '';
    }

    /**
     * Returns elapsed whole hours from a UTC timestamp string.
     */
    private static function hours_since(string $utc): int
    {
        $timestamp = strtotime($utc);

        if ($timestamp === false || $timestamp <= 0) {
            return 0;
        }

        return max(0, (int) floor((time() - $timestamp) / HOUR_IN_SECONDS));
    }

    /**
     * Returns a compact duration label for UI and API consumers.
     */
    private static function duration_label(int $hours): string
    {
        if ($hours >= 48) {
            $days = (int) floor($hours / 24);

            return $days . ' ' . self::plural($days, 'day', 'days');
        }

        return $hours . ' ' . self::plural($hours, 'hour', 'hours');
    }

    /**
     * Returns a short queue-age label.
     */
    private static function queue_age_label(bool $active, string $basis_utc, bool $is_stale, bool $is_urgent, string $duration_label): string
    {
        if (!$active) {
            return 'Not in the active review queue.';
        }

        if ($basis_utc === '') {
            return 'No queue timestamp is available.';
        }

        if ($is_urgent) {
            return 'Urgent: no governance activity for ' . $duration_label . '.';
        }

        if ($is_stale) {
            return 'Stale: no governance activity for ' . $duration_label . '.';
        }

        return 'Fresh: last governance activity was ' . $duration_label . ' ago.';
    }

    /**
     * Returns singular or plural label text.
     */
    private static function plural(int $count, string $singular, string $plural): string
    {
        return $count === 1 ? $singular : $plural;
    }
}