Skip to content

majiayu000/spellbook / skills/threads

threads

Verified

Use when the user explicitly asks for $threads, Codex-native subagents, 开几个子 agent, or a GitHub issue/PR queue needing parallel lanes, worktrees, review/merge gates, and closure audit. Do not use for OS/language threads, chat/email/forum threads, or Assistants product threads unless Codex workflow orchestration is explicit.

FileKindSize
SKILL.mdskill md33.8 KB
agents/openai.yamlconfig671 B
evals/evals.jsonconfig5.7 KB
references/prompt-patterns.mdmarkdown18.7 KB
references/run-log.mdmarkdown16.3 KB
scripts/analyze_run_log.pyexecutablescript8.9 KB
scripts/append_run_log.pyexecutablescript4.0 KB
scripts/run_budget_contract.pyscript17.2 KB
scripts/run_log_schema.pyscript27.5 KB

scripts/run_log_schema.py

View on GitHub
"""Schema, redaction, and validation helpers for threads run logs."""

from __future__ import annotations

import re
from datetime import datetime, timezone
from typing import Any

from run_budget_contract import validate_run_budget, validate_semantic_array_limits


SENSITIVE_KEY_PARTS = (
    "authorization",
    "cookie",
    "password",
    "secret",
    "token",
    "api_key",
    "apikey",
)
SAFE_TOKEN_FIELD_NAMES = {"window_tokens"}
MAX_STRING_LENGTH = 4000
MAX_INPUT_BYTES = 64 * 1024
MAX_DEPTH = 8
MAX_ARRAY_ITEMS = 100
ALLOWED_MODES = {
    "single_agent",
    "plan_only",
    "execute_direct",
    "review_only",
    "research_spec",
    "clarify_first",
}
ALLOWED_TRUTH_LEVELS = {"A", "B", "C", "D"}
ALLOWED_FALLBACK_MODES = {"none", "single_agent", "prompt_pack_only"}
ALLOWED_NATIVE_SUBAGENTS = {"available", "unavailable"}
ALLOWED_SPAWN_REQUIREMENTS = {"required", "optional", "unavailable"}
ALLOWED_DATA_COLLECTION = {"final_report", "local_jsonl", "none"}
ALLOWED_OUTCOMES = {"success", "partial", "blocked", "failed"}
ALLOWED_REMOTE_REFRESH_OWNERS = {"coordinator", "verification_owner"}
ALLOWED_REMOTE_REFRESH_POLICIES = {"continue", "rebase", "required_stop"}
ALLOWED_PR_CLASSIFICATIONS = {
    "merge_ready",
    "review_thread_blocked",
    "ci_failed",
    "conflict_blocked",
    "stale_or_superseded",
    "needs_human_decision",
}
ALLOWED_ISSUE_TO_PR_STATUSES = {
    "covered",
    "uncovered",
    "stale_or_superseded",
    "needs_human_decision",
}
ALLOWED_LANE_ROLES = {
    "planner",
    "worker",
    "reviewer",
    "merge_reviewer",
    "researcher",
    "fix_worker",
    "closure_auditor",
}
ALLOWED_VERIFICATION_SCOPES = {"inspection_only", "targeted", "full_local", "ci_only"}
ALLOWED_NATIVE_SPAWN_TOOLS = {"multi_agent_v1.spawn_agent"}
ALLOWED_CONNECTOR_REVIEW_STATUSES = {
    "completed",
    "no_connector_expected",
    "pending",
    "unknown",
}
ALLOWED_REVIEW_LOOP_OUTCOMES = {"resolved", "review_loop", "not_applicable"}
ALLOWED_RAW_LOG_POLICIES = {"file_only", "summary_only", "not_applicable"}
INVALID_AGENT_IDS = {"", "none", "n/a", "na", "null", "main", "main_thread", "coordinator"}
ALLOWED_SINGLE_AGENT_REASONS = {
    "no_independent_lanes",
    "sequential_dependency",
    "shared_writable_files",
    "tool_unavailable",
    "user_requested_single_agent",
}
ALLOWED_TOP_LEVEL_FIELDS = {
    "schema_version",
    "recorded_at_utc",
    "run_phase",
    "skill",
    "skill_source",
    "active_skill_source",
    "mode",
    "repo",
    "base_ref",
    "trigger_summary",
    "goal",
    "non_goals",
    "intent_contract",
    "merge_policy",
    "data_collection",
    "truth_level",
    "native_subagents",
    "explicit_thread_request",
    "spawn_requirement",
    "native_thread_evidence",
    "fallback_mode",
    "no_spawn_reason",
    "single_agent_justification",
    "capability_gate",
    "thread_dispatch_gate",
    "queue_gate",
    "queue_bounds",
    "context_budget",
    "output_firewall",
    "remote_refresh",
    "queue_ledger",
    "lane_map",
    "lanes_total",
    "lanes",
    "failure_codes",
    "remote_truth",
    "remote_closure",
    "connector_review",
    "closure_audit",
    "local_state",
    "ci_wait",
    "review_loop",
    "run_log",
    "exclusive_verification",
    "verification",
    "outcome",
    "notes",
}
ALLOWED_FAILURE_CODES = {
    "trigger_too_broad",
    "missing_intent_contract",
    "durable_log_skipped",
    "truth_level_too_low",
    "source_drift",
    "active_skill_source_unknown",
    "stale_remote_state",
    "stale_base",
    "duplicate_work_missed",
    "contributor_pr_replaced_unnecessarily",
    "role_drift",
    "write_scope_violation",
    "vague_lane_output",
    "verification_gap",
    "raw_output_blocked",
    "parent_context_hard_stop",
    "review_thread_missed",
    "connector_review_incomplete",
    "review_loop",
    "native_thread_not_spawned",
    "waiting_ci",
    "merge_gate_bypass",
    "tool_unavailable",
    "environment_mismatch",
    "context_loss",
    "user_interrupt",
}
SENSITIVE_ENV_ASSIGNMENT_PATTERN = re.compile(
    r"(?i)\b([A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*)"
    r"\s*=\s*([^\s,;]+)"
)

SENSITIVE_PATTERNS = (
    re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----", re.DOTALL),
    re.compile(r"github_pat_[A-Za-z0-9_]{20,}"),
    re.compile(r"gh[pousr]_[A-Za-z0-9_]{20,}"),
    re.compile(r"sk-[A-Za-z0-9_-]{20,}"),
    re.compile(r"AKIA[0-9A-Z]{16}"),
    re.compile(r"(?i)bearer\s+[A-Za-z0-9._~+/=-]{16,}"),
    re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b"),
)


def redact_string(value: str) -> str:
    redacted = SENSITIVE_ENV_ASSIGNMENT_PATTERN.sub(r"\1=[REDACTED]", value)
    for pattern in SENSITIVE_PATTERNS:
        redacted = pattern.sub("[REDACTED]", redacted)
    if len(redacted) > MAX_STRING_LENGTH:
        return redacted[:MAX_STRING_LENGTH] + "...[TRUNCATED]"
    return redacted


def redact(value: Any, key_hint: str = "", depth: int = 0) -> Any:
    if depth > MAX_DEPTH:
        return "[TRUNCATED_DEPTH]"
    lower_key = key_hint.lower()
    if (
        lower_key not in SAFE_TOKEN_FIELD_NAMES
        and any(part in lower_key for part in SENSITIVE_KEY_PARTS)
    ):
        return "[REDACTED]"
    if isinstance(value, dict):
        return {str(key): redact(item, str(key), depth + 1) for key, item in value.items()}
    if isinstance(value, list):
        return [redact(item, key_hint, depth + 1) for item in value[:MAX_ARRAY_ITEMS]]
    if isinstance(value, str):
        return redact_string(value)
    return value


def normalize_record(raw: Any, allow_extra: bool = False) -> dict[str, Any]:
    if not isinstance(raw, dict):
        raise ValueError("run log input must be a JSON object")
    unknown_fields = sorted(set(raw) - ALLOWED_TOP_LEVEL_FIELDS)
    if unknown_fields and not allow_extra:
        raise ValueError("unknown top-level field(s): " + ", ".join(unknown_fields))
    validate_semantic_array_limits(raw, MAX_ARRAY_ITEMS)

    record = redact(raw)
    record.setdefault("run_phase", "final")
    mode = record.get("mode")
    if mode is not None and mode not in ALLOWED_MODES:
        raise ValueError(f"unknown mode: {mode}")
    truth_level = record.get("truth_level")
    if truth_level is not None and truth_level not in ALLOWED_TRUTH_LEVELS:
        raise ValueError(f"unknown truth_level: {truth_level}")
    validate_enum_fields(record)
    validate_native_thread_evidence(record)
    validate_run_budget(record)

    record.setdefault("schema_version", 1)
    record["recorded_at_utc"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
    return record


def validate_enum(value: Any, allowed: set[str], field: str) -> None:
    if value is not None and value not in allowed:
        raise ValueError(f"unknown {field}: {value}")


def require_object(value: Any, field: str) -> dict[str, Any]:
    if not isinstance(value, dict):
        raise ValueError(f"{field} must be an object")
    return value


def require_list(value: Any, field: str) -> list[Any]:
    if not isinstance(value, list):
        raise ValueError(f"{field} must be a list")
    return value


def validate_bool(value: Any, field: str) -> None:
    if value is not None and not isinstance(value, bool):
        raise ValueError(f"{field} must be a boolean")


def validate_non_negative_int(value: Any, field: str) -> None:
    if value is not None and (not isinstance(value, int) or isinstance(value, bool) or value < 0):
        raise ValueError(f"{field} must be a non-negative integer")


def validate_positive_int(value: Any, field: str) -> None:
    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
        raise ValueError(f"{field} must be a positive integer")


def validate_non_negative_number(value: Any, field: str) -> None:
    if value is None:
        return
    if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
        raise ValueError(f"{field} must be a non-negative number")


def validate_ratio(value: Any, field: str) -> None:
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        raise ValueError(f"{field} must be a number")
    if value <= 0 or value >= 1:
        raise ValueError(f"{field} must be between 0 and 1")


def validate_non_empty_string(value: Any, field: str) -> None:
    if not isinstance(value, str) or not value.strip():
        raise ValueError(f"{field} must be a non-empty string")


def validate_string_list(value: Any, field: str) -> None:
    for item in require_list(value, field):
        if not isinstance(item, str) or not item.strip():
            raise ValueError(f"{field} entries must be non-empty strings")


def validate_context_budget_object(context_budget: Any, field_prefix: str) -> None:
    if context_budget is None:
        return
    budget = require_object(context_budget, field_prefix)
    for field in (
        "window_tokens",
        "soft_stop_ratio",
        "hard_stop_ratio",
        "critical_stop_ratio",
    ):
        if field not in budget:
            raise ValueError(f"{field_prefix}.{field} is required when {field_prefix} is present")
    validate_positive_int(budget.get("window_tokens"), f"{field_prefix}.window_tokens")
    for field in ("soft_stop_ratio", "hard_stop_ratio", "critical_stop_ratio"):
        validate_ratio(budget[field], f"{field_prefix}.{field}")
    soft = budget["soft_stop_ratio"]
    hard = budget["hard_stop_ratio"]
    critical = budget["critical_stop_ratio"]
    if not soft < hard < critical:
        raise ValueError(
            f"{field_prefix} ratios must satisfy soft_stop_ratio < "
            "hard_stop_ratio < critical_stop_ratio"
        )


def validate_context_budget(record: dict[str, Any]) -> None:
    validate_context_budget_object(record.get("context_budget"), "context_budget")
    intent_contract = record.get("intent_contract")
    if isinstance(intent_contract, dict):
        validate_context_budget_object(
            intent_contract.get("context_budget"),
            "intent_contract.context_budget",
        )


def validate_output_firewall_object(output_firewall: Any, field_prefix: str) -> None:
    if output_firewall is None:
        return
    firewall = require_object(output_firewall, field_prefix)
    if "raw_log_policy" not in firewall:
        raise ValueError(f"{field_prefix}.raw_log_policy is required when {field_prefix} is present")
    validate_enum(
        firewall.get("raw_log_policy"),
        ALLOWED_RAW_LOG_POLICIES,
        f"{field_prefix}.raw_log_policy",
    )
    for field in ("max_parent_stdout_lines", "max_subagent_final_lines"):
        validate_non_negative_int(firewall.get(field), f"{field_prefix}.{field}")
    if firewall.get("raw_log_policy") == "file_only":
        validate_non_empty_string(firewall.get("artifact_root"), f"{field_prefix}.artifact_root")
    if "evidence_paths" in firewall:
        validate_string_list(firewall["evidence_paths"], f"{field_prefix}.evidence_paths")


def validate_output_firewall(record: dict[str, Any]) -> None:
    validate_output_firewall_object(record.get("output_firewall"), "output_firewall")
    intent_contract = record.get("intent_contract")
    if isinstance(intent_contract, dict):
        validate_output_firewall_object(
            intent_contract.get("output_firewall"),
            "intent_contract.output_firewall",
        )


def validate_failure_codes(record: dict[str, Any]) -> None:
    failure_codes = record.get("failure_codes")
    if failure_codes is None:
        return
    require_list(failure_codes, "failure_codes")
    unknown = sorted(
        code
        for code in failure_codes
        if not isinstance(code, str) or code not in ALLOWED_FAILURE_CODES
    )
    if unknown:
        raise ValueError("unknown failure_codes: " + ", ".join(map(str, unknown)))


def validate_lane_entries(lanes: Any, field: str) -> None:
    for lane in require_list(lanes, field):
        lane_object = require_object(lane, f"{field} entries")
        validate_enum(lane_object.get("role"), ALLOWED_LANE_ROLES, f"{field}.role")
        validate_enum(
            lane_object.get("verification_scope"),
            ALLOWED_VERIFICATION_SCOPES,
            f"{field}.verification_scope",
        )


def validate_lanes(record: dict[str, Any]) -> None:
    lanes = record.get("lanes")
    if lanes is not None:
        validate_lane_entries(lanes, "lanes")


def validate_enum_fields(record: dict[str, Any]) -> None:
    validate_enum(nested_get(record, "native_subagents"), ALLOWED_NATIVE_SUBAGENTS, "native_subagents")
    validate_enum(
        nested_get(record, "spawn_requirement"),
        ALLOWED_SPAWN_REQUIREMENTS,
        "spawn_requirement",
    )
    validate_enum(record.get("data_collection"), ALLOWED_DATA_COLLECTION, "data_collection")
    intent_contract = record.get("intent_contract")
    if isinstance(intent_contract, dict):
        validate_enum(
            intent_contract.get("data_collection"),
            ALLOWED_DATA_COLLECTION,
            "intent_contract.data_collection",
        )
        for field in ("authorized_actions", "fresh_confirmation_required"):
            if field in intent_contract:
                validate_string_list(intent_contract[field], f"intent_contract.{field}")
    validate_enum(record.get("outcome"), ALLOWED_OUTCOMES, "outcome")
    validate_queue_gate(record)
    validate_queue_ledger(record)
    validate_lane_map(record)
    validate_remote_closure(record)
    validate_connector_review(record)
    validate_ci_wait(record)
    validate_review_loop(record)
    validate_context_budget(record)
    validate_output_firewall(record)
    validate_failure_codes(record)
    validate_lanes(record)


def remote_refresh_contract(record: dict[str, Any]) -> dict[str, Any] | None:
    remote_refresh = record.get("remote_refresh")
    if isinstance(remote_refresh, dict):
        return remote_refresh
    queue_gate = record.get("queue_gate")
    if isinstance(queue_gate, dict):
        nested = queue_gate.get("remote_refresh")
        if isinstance(nested, dict):
            return nested
    return None


def validate_queue_gate(record: dict[str, Any]) -> None:
    queue_gate = record.get("queue_gate")
    if queue_gate is None:
        return
    require_object(queue_gate, "queue_gate")

    queue_truth_level = queue_gate.get("truth_level")
    validate_enum(queue_truth_level, ALLOWED_TRUTH_LEVELS, "queue_gate.truth_level")
    top_truth_level = record.get("truth_level")
    if (
        top_truth_level is not None
        and queue_truth_level is not None
        and top_truth_level != queue_truth_level
    ):
        raise ValueError("conflicting truth_level values across top-level and queue_gate")

    remote_refresh = remote_refresh_contract(record)
    if remote_refresh is None:
        raise ValueError("remote_refresh is required when queue_gate is present")
    for field in ("owner_lane", "policy", "origin_main_sha", "local_base_sha", "stale_base"):
        if field not in remote_refresh:
            raise ValueError(f"remote_refresh.{field} is required when queue_gate is present")
    validate_enum(
        remote_refresh.get("owner_lane"),
        ALLOWED_REMOTE_REFRESH_OWNERS,
        "remote_refresh.owner_lane",
    )
    validate_enum(
        remote_refresh.get("policy"),
        ALLOWED_REMOTE_REFRESH_POLICIES,
        "remote_refresh.policy",
    )
    validate_bool(remote_refresh.get("stale_base"), "remote_refresh.stale_base")

    pr_classification = queue_gate.get("pr_classification", [])
    if pr_classification is not None:
        validate_pr_classification(pr_classification)
    validate_issue_to_pr_map(queue_gate.get("issue_to_pr_map"))
    for field in ("open_prs", "open_issues"):
        if field in queue_gate:
            require_list(queue_gate[field], f"queue_gate.{field}")


def validate_pr_classification(pr_classification: Any) -> None:
    for item in require_list(pr_classification, "queue_gate.pr_classification"):
        entry = require_object(item, "queue_gate.pr_classification entries")
        validate_enum(
            entry.get("classification"),
            ALLOWED_PR_CLASSIFICATIONS,
            "queue_gate.pr_classification.classification",
        )


def validate_issue_to_pr_map(issue_to_pr_map: Any) -> None:
    if issue_to_pr_map is None:
        return
    for item in require_list(issue_to_pr_map, "queue_gate.issue_to_pr_map"):
        entry = require_object(item, "queue_gate.issue_to_pr_map entries")
        if "issue" not in entry:
            raise ValueError("queue_gate.issue_to_pr_map.issue is required")
        if "status" not in entry:
            raise ValueError("queue_gate.issue_to_pr_map.status is required")
        validate_enum(
            entry.get("status"),
            ALLOWED_ISSUE_TO_PR_STATUSES,
            "queue_gate.issue_to_pr_map.status",
        )


def validate_queue_ledger(record: dict[str, Any]) -> None:
    queue_ledger = record.get("queue_ledger")
    if queue_ledger is None:
        return
    if isinstance(queue_ledger, list):
        for item in queue_ledger:
            require_object(item, "queue_ledger entries")
        return
    ledger = require_object(queue_ledger, "queue_ledger")
    for field in ("items_total", "items_closed", "items_deferred"):
        value = ledger.get(field)
        if field in ledger and value is None:
            raise ValueError(f"queue_ledger.{field} must be a non-negative integer")
        validate_non_negative_int(value, f"queue_ledger.{field}")
    validate_bool(ledger.get("stale_base"), "queue_ledger.stale_base")
    if "superseded_items" in ledger:
        require_list(ledger["superseded_items"], "queue_ledger.superseded_items")
    if "items" in ledger:
        for item in require_list(ledger["items"], "queue_ledger.items"):
            require_object(item, "queue_ledger.items entries")


def validate_lane_map(record: dict[str, Any]) -> None:
    lane_map = record.get("lane_map")
    if lane_map is None:
        return
    lane_map_object = require_object(lane_map, "lane_map")
    if "lanes" in lane_map_object:
        validate_lane_entries(lane_map_object["lanes"], "lane_map.lanes")


def validate_remote_closure(record: dict[str, Any]) -> None:
    remote_closure = record.get("remote_closure")
    if remote_closure is None:
        return
    closure = require_object(remote_closure, "remote_closure")
    validate_bool(closure.get("checked"), "remote_closure.checked")
    for field in ("open_prs", "open_issues", "unresolved_review_threads"):
        validate_non_negative_int(closure.get(field), f"remote_closure.{field}")


def validate_connector_review(record: dict[str, Any]) -> None:
    connector_review = record.get("connector_review")
    if connector_review is None:
        return
    review = require_object(connector_review, "connector_review")
    validate_bool(review.get("expected"), "connector_review.expected")
    validate_enum(
        review.get("status"),
        ALLOWED_CONNECTOR_REVIEW_STATUSES,
        "connector_review.status",
    )
    if "head_sha" in review and not isinstance(review["head_sha"], str):
        raise ValueError("connector_review.head_sha must be a string")


def validate_ci_wait(record: dict[str, Any]) -> None:
    ci_wait = record.get("ci_wait")
    if ci_wait is None:
        return
    wait = require_object(ci_wait, "ci_wait")
    validate_non_negative_number(wait.get("duration_seconds"), "ci_wait.duration_seconds")
    validate_bool(wait.get("budget_exhausted"), "ci_wait.budget_exhausted")
    if "pending_checks" in wait:
        require_list(wait["pending_checks"], "ci_wait.pending_checks")


def validate_review_loop(record: dict[str, Any]) -> None:
    review_loop = record.get("review_loop")
    if review_loop is None:
        return
    loop = require_object(review_loop, "review_loop")
    validate_non_negative_int(loop.get("cycles"), "review_loop.cycles")
    validate_enum(loop.get("outcome"), ALLOWED_REVIEW_LOOP_OUTCOMES, "review_loop.outcome")


def truthy(value: Any) -> bool:
    if isinstance(value, bool):
        return value
    if isinstance(value, str):
        return value.strip().lower() in {"yes", "true", "1", "required"}
    return False


def canonical_gate_value(field: str, value: Any) -> Any:
    if field == "explicit_thread_request":
        return truthy(value)
    return value


def nested_get(mapping: dict[str, Any], field: str) -> Any:
    values: list[tuple[str, Any]] = []
    if field in mapping:
        values.append(("top-level", mapping.get(field)))
    for container in ("capability_gate", "thread_dispatch_gate"):
        nested = mapping.get(container)
        if isinstance(nested, dict) and field in nested:
            values.append((container, nested.get(field)))

    present = [(source, value) for source, value in values if value is not None]
    if not present:
        return None
    canonical_values = {
        canonical_gate_value(field, value)
        for _, value in present
    }
    if len(canonical_values) > 1:
        sources = ", ".join(source for source, _ in present)
        raise ValueError(f"conflicting {field} values across {sources}")
    return present[0][1]


def native_thread_evidence(record: dict[str, Any]) -> dict[str, Any] | None:
    evidence = record.get("native_thread_evidence")
    if isinstance(evidence, dict):
        return evidence
    dispatch_gate = record.get("thread_dispatch_gate")
    if isinstance(dispatch_gate, dict):
        nested = dispatch_gate.get("native_thread_evidence")
        if isinstance(nested, dict):
            return nested
    return None


def thread_dispatch_gate(record: dict[str, Any]) -> dict[str, Any] | None:
    gate = record.get("thread_dispatch_gate")
    return gate if isinstance(gate, dict) else None


def valid_agent_id(value: Any) -> bool:
    if not isinstance(value, str):
        return False
    return value.strip().lower() not in INVALID_AGENT_IDS


def valid_spawned_agents(record: dict[str, Any]) -> list[dict[str, Any]]:
    evidence = native_thread_evidence(record)
    if evidence is None:
        return []
    spawned_agents = evidence.get("spawned_agents")
    if not isinstance(spawned_agents, list):
        return []
    valid_agents = []
    for agent in spawned_agents:
        if not isinstance(agent, dict):
            continue
        agent_id = agent.get("agent_id_or_thread_id") or agent.get("tool_agent_id")
        if (
            agent.get("spawn_tool") in ALLOWED_NATIVE_SPAWN_TOOLS
            and valid_agent_id(agent_id)
            and agent.get("result_collected") is True
            and bool(agent.get("wait_evidence"))
            and bool(agent.get("close_evidence"))
        ):
            valid_agents.append(agent)
    return valid_agents


def has_spawned_agent(record: dict[str, Any]) -> bool:
    return bool(valid_spawned_agents(record))


def normalize_reason(value: Any) -> str | None:
    if not isinstance(value, str):
        return None
    normalized = value.strip().lower().replace("-", "_").replace(" ", "_")
    return normalized or None


def allowed_reason(reason: Any, evidence: Any = None) -> bool:
    normalized = normalize_reason(reason)
    if normalized not in ALLOWED_SINGLE_AGENT_REASONS:
        return False
    return evidence is None or bool(evidence)


def has_single_agent_reason(record: dict[str, Any]) -> bool:
    no_spawn_reason = record.get("no_spawn_reason")
    if isinstance(no_spawn_reason, dict):
        if allowed_reason(no_spawn_reason.get("reason"), no_spawn_reason.get("evidence")):
            return True
    elif allowed_reason(no_spawn_reason):
        return True

    gate = thread_dispatch_gate(record)
    if gate is not None:
        gate_reason = gate.get("no_spawn_reason")
        if isinstance(gate_reason, dict):
            if allowed_reason(gate_reason.get("reason"), gate_reason.get("evidence")):
                return True
        elif allowed_reason(gate_reason):
            return True

    justification = record.get("single_agent_justification")
    if (
        isinstance(justification, dict)
        and allowed_reason(justification.get("reason"), justification.get("evidence"))
    ):
        return True

    evidence = native_thread_evidence(record)
    if not isinstance(evidence, dict):
        return False
    return allowed_reason(evidence.get("fallback_reason"))


def lane_has_no_spawn_reason(lane: dict[str, Any]) -> bool:
    reason = lane.get("no_spawn_reason")
    if isinstance(reason, dict):
        return allowed_reason(reason.get("reason"), reason.get("evidence"))
    return allowed_reason(reason)


def validate_planned_native_threads(record: dict[str, Any]) -> None:
    gate = thread_dispatch_gate(record)
    if gate is None:
        return
    planned_threads = gate.get("planned_native_threads")
    if planned_threads is None:
        return
    if not isinstance(planned_threads, list):
        raise ValueError("thread_dispatch_gate.planned_native_threads must be a list")

    spawned_lane_ids = {
        agent.get("lane_id")
        for agent in valid_spawned_agents(record)
        if isinstance(agent.get("lane_id"), str) and agent.get("lane_id")
    }
    missing_reasons = []
    for lane in planned_threads:
        if not isinstance(lane, dict):
            raise ValueError("thread_dispatch_gate.planned_native_threads entries must be objects")
        lane_id = lane.get("id") or lane.get("lane_id")
        if not lane_id:
            raise ValueError("thread_dispatch_gate.planned_native_threads entries require id")
        if lane_id in spawned_lane_ids:
            continue
        if lane_has_no_spawn_reason(lane):
            continue
        missing_reasons.append(str(lane_id))

    if missing_reasons:
        raise ValueError(
            "thread_dispatch_gate.planned_native_threads missing spawned evidence "
            "or no_spawn_reason for lane(s): " + ", ".join(missing_reasons)
        )


def validate_native_thread_evidence(record: dict[str, Any]) -> None:
    mode = record.get("mode")
    native_subagents = nested_get(record, "native_subagents")
    fallback_mode = nested_get(record, "fallback_mode")
    explicit_request = nested_get(record, "explicit_thread_request")
    spawn_requirement = nested_get(record, "spawn_requirement")
    dispatch_mode = mode in {
        "single_agent",
        "plan_only",
        "execute_direct",
        "review_only",
        "research_spec",
    }
    required = truthy(explicit_request) or spawn_requirement == "required"

    if fallback_mode is not None and fallback_mode not in ALLOWED_FALLBACK_MODES:
        raise ValueError(f"unknown fallback_mode: {fallback_mode}")
    explicit_native_required = dispatch_mode and native_subagents == "available" and required

    if explicit_native_required and fallback_mode is None:
        raise ValueError(
            "fallback_mode is required when native subagents are available "
            "for an explicit threads run"
        )

    if (
        explicit_native_required
        and fallback_mode == "none"
        and record.get("run_phase") != "preflight"
        and not has_spawned_agent(record)
    ):
        raise ValueError(
            "native_thread_evidence.spawned_agents is required when native "
            "subagents are available for an explicit threads run"
        )

    if (
        explicit_native_required
        and fallback_mode == "single_agent"
        and not has_single_agent_reason(record)
    ):
        raise ValueError(
            "single_agent fallback for an explicit threads run requires "
            "an allowed no_spawn_reason or single_agent_justification.reason"
        )

    if explicit_native_required and fallback_mode == "prompt_pack_only":
        raise ValueError(
            "prompt_pack_only fallback is invalid when native subagents are "
            "available for an explicit threads run"
        )

    if record.get("run_phase") == "preflight":
        return

    if explicit_native_required and fallback_mode == "none":
        validate_planned_native_threads(record)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall