claude-dev-env 2.7.1 → 2.9.0

package/scripts/dev_env_scripts_constants/code_review_constants.py

@@ -1,15 +1,20 @@
-"""Named constants for the host-aware `/code-review` invoker.
+"""Named constants for the host-aware `/code-review` invoker and review loop.
 
 ::
 
     ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
         ok: ("low", "medium", "high", "xhigh", "max")
         flag: "ultra"  (rejected; needs an interactive terminal)
+    ALL_FINDING_SEVERITIES
+        ok: ("blocker", "high", "medium", "low", "nit")
+    ALL_LOOP_TERMINALS
+        ok: ("clean", "nits_fixed", "advisor_blocked")
     RECORD_STAMP_FLAG
         ok: "--record-stamp"
 
 Effort tokens re-export the hooks enforcement constants (single source).
-Scalar flags, JSON keys, and mint-loop messages live here for the invoker.
+Scalar flags, JSON keys, mint-loop messages, finding severity vocabulary,
+reviewed-head counting, and loop terminal resolution live here.
 """
 
 from __future__ import annotations
@@ -17,6 +22,7 @@ from __future__ import annotations
 import importlib.util
 import os
 import sys
+from collections.abc import Mapping, Sequence
 from pathlib import Path
 from types import ModuleType
 
@@ -223,3 +229,398 @@ STAMP_STORE_RECORD_CLEAN_STAMP_NAME: str = "record_clean_stamp"
 
 STAMP_STORE_RESOLVE_REPO_ROOT_NAME: str = "resolve_repo_root"
 """Attribute name of the repo-root resolver on the stamp store module."""
+
+SEVERITY_BLOCKER: str = "blocker"
+"""Finding severity for a release-blocking defect."""
+
+SEVERITY_HIGH: str = "high"
+"""Finding severity for a high-impact defect that is not a release blocker."""
+
+SEVERITY_MEDIUM: str = "medium"
+"""Finding severity for a moderate maintainer-action defect."""
+
+SEVERITY_LOW: str = "low"
+"""Finding severity for a low-impact non-nit defect."""
+
+SEVERITY_NIT: str = "nit"
+"""Finding severity for a mechanical clarity, format, or typo fix only."""
+
+ALL_FINDING_SEVERITIES: tuple[str, ...] = (
+    SEVERITY_BLOCKER,
+    SEVERITY_HIGH,
+    SEVERITY_MEDIUM,
+    SEVERITY_LOW,
+    SEVERITY_NIT,
+)
+"""Frozen severity vocabulary every retained finding must use."""
+
+VERDICT_CONFIRMED: str = "CONFIRMED"
+"""Verification verdict when the trigger and wrong outcome are named."""
+
+VERDICT_PLAUSIBLE: str = "PLAUSIBLE"
+"""Verification verdict when the mechanism is real and the trigger is uncertain."""
+
+VERDICT_REFUTED: str = "REFUTED"
+"""Verification verdict when the candidate is factually wrong or guarded."""
+
+ALL_VERIFICATION_VERDICTS: tuple[str, ...] = (
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+    VERDICT_REFUTED,
+)
+"""Frozen verification-verdict vocabulary from the medium verify phase."""
+
+ALL_RETAINED_VERIFICATION_VERDICTS: tuple[str, ...] = (
+    VERDICT_CONFIRMED,
+    VERDICT_PLAUSIBLE,
+)
+"""Verdicts that keep a candidate in the retained findings list."""
+
+TERMINAL_CLEAN: str = "clean"
+"""Loop terminal when a reviewed head retains zero findings."""
+
+TERMINAL_NITS_FIXED: str = "nits_fixed"
+"""Loop terminal when every retained finding is a fixed nit after gates."""
+
+TERMINAL_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Loop terminal when classification needs an advisor that cannot be reached."""
+
+ALL_LOOP_TERMINALS: tuple[str, ...] = (
+    TERMINAL_CLEAN,
+    TERMINAL_NITS_FIXED,
+    TERMINAL_ADVISOR_BLOCKED,
+)
+"""Frozen set of review-loop terminal statuses."""
+
+FINDING_FIELD_SEVERITY: str = "severity"
+"""Structured finding field that holds one of ``ALL_FINDING_SEVERITIES``."""
+
+FINDING_FIELD_VERDICT: str = "verdict"
+"""Structured finding field that holds a verification verdict."""
+
+RESULT_KEY_TERMINAL: str = "terminal"
+"""JSON result key naming the review-loop terminal status."""
+
+RESULT_KEY_DRAFT_PRESERVED: str = "draft_preserved"
+"""JSON result key holding whether the pull request stays draft."""
+
+RESULT_KEY_REVIEWED_HEAD_COUNT: str = "reviewed_head_count"
+"""JSON result key holding how many distinct heads the loop reviewed."""
+
+RESULT_KEY_SURVIVING_FINDINGS: str = "surviving_findings"
+"""JSON result key holding structured findings that remain at terminal."""
+
+
+def is_known_finding_severity(severity: str) -> bool:
+    """Return whether ``severity`` is one of the frozen five tokens.
+
+    ::
+
+        is_known_finding_severity("nit")      # ok: True
+        is_known_finding_severity("P1")       # flag: False
+        is_known_finding_severity("")         # flag: False
+
+    Args:
+        severity: Candidate severity token from a structured finding.
+
+    Returns:
+        True when ``severity`` is in ``ALL_FINDING_SEVERITIES``.
+    """
+    return severity in ALL_FINDING_SEVERITIES
+
+
+def is_nit_finding_severity(severity: str) -> bool:
+    """Return whether ``severity`` is exactly the nit token.
+
+    ::
+
+        is_nit_finding_severity("nit")   # ok: True
+        is_nit_finding_severity("low")   # flag: False
+
+    Args:
+        severity: Candidate severity token from a structured finding.
+
+    Returns:
+        True when ``severity`` equals ``SEVERITY_NIT``.
+    """
+    return severity == SEVERITY_NIT
+
+
+def is_retained_verification_verdict(verdict: str) -> bool:
+    """Return whether ``verdict`` keeps a finding in the retained set.
+
+    ::
+
+        is_retained_verification_verdict("CONFIRMED")  # ok: True
+        is_retained_verification_verdict("REFUTED")    # flag: False
+
+    Args:
+        verdict: Verification vote from the medium verify phase.
+
+    Returns:
+        True when ``verdict`` is CONFIRMED or PLAUSIBLE.
+    """
+    return verdict in ALL_RETAINED_VERIFICATION_VERDICTS
+
+
+def finding_carries_severity_and_verdict(
+    *,
+    severity: object,
+    verdict: object,
+) -> bool:
+    """Return whether one retained finding carries both required fields.
+
+    ::
+
+        finding_carries_severity_and_verdict(
+            severity="high", verdict="CONFIRMED"
+        )  # ok: True
+        finding_carries_severity_and_verdict(
+            severity="high", verdict=None
+        )  # flag: False
+
+    A retained finding needs a known severity and a retained verification
+    verdict. Missing either field, or a REFUTED verdict, fails the contract.
+
+    Args:
+        severity: Severity token from a structured finding, or missing value.
+        verdict: Verification verdict from a structured finding, or missing.
+
+    Returns:
+        True when severity and retained verdict are both present and valid.
+    """
+    if not isinstance(severity, str) or not isinstance(verdict, str):
+        return False
+    if not is_known_finding_severity(severity):
+        return False
+    return is_retained_verification_verdict(verdict)
+
+
+def all_findings_carry_severity_and_verdict(
+    all_findings: Sequence[Mapping[str, object]],
+) -> bool:
+    """Return whether every finding carries severity and a retained verdict.
+
+    ::
+
+        all_findings_carry_severity_and_verdict([])  # ok: True
+        all_findings_carry_severity_and_verdict(
+            [{"severity": "nit", "verdict": "CONFIRMED"}]
+        )  # ok: True
+
+    Args:
+        all_findings: Structured findings retained after verification.
+
+    Returns:
+        True when every finding passes ``finding_carries_severity_and_verdict``.
+    """
+    for each_finding in all_findings:
+        if not finding_carries_severity_and_verdict(
+            severity=each_finding.get(FINDING_FIELD_SEVERITY),
+            verdict=each_finding.get(FINDING_FIELD_VERDICT),
+        ):
+            return False
+    return True
+
+
+def has_unclassified_finding(all_findings: Sequence[Mapping[str, object]]) -> bool:
+    """Return whether any finding lacks a known severity token.
+
+    ::
+
+        has_unclassified_finding([{"verdict": "CONFIRMED"}])  # ok: True
+        has_unclassified_finding(
+            [{"severity": "nit", "verdict": "CONFIRMED"}]
+        )  # flag: False
+
+    Args:
+        all_findings: Structured findings under terminal evaluation.
+
+    Returns:
+        True when any finding omits severity or uses an unknown token.
+    """
+    for each_finding in all_findings:
+        severity = each_finding.get(FINDING_FIELD_SEVERITY)
+        if not isinstance(severity, str):
+            return True
+        if not is_known_finding_severity(severity):
+            return True
+    return False
+
+
+def has_non_nit_finding(all_findings: Sequence[Mapping[str, object]]) -> bool:
+    """Return whether any finding carries a known non-nit severity.
+
+    ::
+
+        has_non_nit_finding([{"severity": "high"}])  # ok: True
+        has_non_nit_finding([{"severity": "nit"}])   # flag: False
+
+    Args:
+        all_findings: Structured findings under terminal evaluation.
+
+    Returns:
+        True when any finding's severity is known and not ``nit``.
+    """
+    for each_finding in all_findings:
+        severity = each_finding.get(FINDING_FIELD_SEVERITY)
+        if not isinstance(severity, str):
+            continue
+        if not is_known_finding_severity(severity):
+            continue
+        if not is_nit_finding_severity(severity):
+            return True
+    return False
+
+
+def is_nits_only_findings(all_findings: Sequence[Mapping[str, object]]) -> bool:
+    """Return whether every finding is a classified nit and at least one exists.
+
+    ::
+
+        is_nits_only_findings([{"severity": "nit"}])  # ok: True
+        is_nits_only_findings([])                      # flag: False
+        is_nits_only_findings(
+            [{"severity": "nit"}, {"severity": "high"}]
+        )  # flag: False
+
+    An empty list is clean, not nits-only. Unclassified findings fail the
+    nits-only check so they route to classification before a terminal.
+
+    Args:
+        all_findings: Structured findings under terminal evaluation.
+
+    Returns:
+        True when the list is non-empty, fully classified, and all nits.
+    """
+    if not all_findings:
+        return False
+    if has_unclassified_finding(all_findings):
+        return False
+    return not has_non_nit_finding(all_findings)
+
+
+def record_reviewed_head(
+    all_reviewed_head_shas: tuple[str, ...],
+    head_sha: str,
+) -> tuple[str, ...]:
+    """Append ``head_sha`` once when it is a new distinct head.
+
+    ::
+
+        record_reviewed_head((), "aaa")           # ok: ("aaa",)
+        record_reviewed_head(("aaa",), "aaa")     # ok: ("aaa",)  re-review
+        record_reviewed_head(("a", "b", "c"), "d")  # ok: ("a", "b", "c", "d")
+
+    A re-review of the same head does not increment the count. There is no
+    head count limit — every new head is recorded.
+
+    Args:
+        all_reviewed_head_shas: Ordered distinct heads already reviewed.
+        head_sha: Git head under review for this pass.
+
+    Returns:
+        The prior tuple, or the prior tuple plus ``head_sha`` when new.
+    """
+    if head_sha in all_reviewed_head_shas:
+        return all_reviewed_head_shas
+    return all_reviewed_head_shas + (head_sha,)
+
+
+def resolve_review_loop_terminal(
+    *,
+    all_findings: Sequence[Mapping[str, object]],
+    reviewed_head_count: int,
+    is_gates_passed: bool,
+    is_nits_applied: bool,
+    is_advisor_unreachable: bool = False,
+) -> str | None:
+    """Resolve the review-loop terminal, or None when the loop continues.
+
+    ::
+
+        resolve_review_loop_terminal(
+            all_findings=(), reviewed_head_count=1,
+            is_gates_passed=True, is_nits_applied=False,
+        )  # ok: "clean"
+        resolve_review_loop_terminal(
+            all_findings=(), reviewed_head_count=1,
+            is_gates_passed=False, is_nits_applied=False,
+        )  # flag: None  (gates still open)
+        resolve_review_loop_terminal(
+            all_findings=[{"severity": "high", "verdict": "CONFIRMED"}],
+            reviewed_head_count=5, is_gates_passed=True, is_nits_applied=False,
+        )  # flag: None  (open non-nit work continues)
+
+    Empty findings return clean only when gates pass. Nits-only findings
+    return nits_fixed after each finding carries severity and a retained
+    verdict, the nits are applied, and gates pass. An unreachable advisor
+    needed for classification returns advisor_blocked. Open non-nit work
+    returns None so the caller re-enters. There is no head-count stop.
+
+    Args:
+        all_findings: Structured findings retained for this head.
+        reviewed_head_count: Distinct heads reviewed so far, including this one.
+        is_gates_passed: Whether required checks passed for this decision.
+        is_nits_applied: Whether every nit on the target was fixed.
+        is_advisor_unreachable: Whether classification needs a missing advisor.
+
+    Returns:
+        One of ``ALL_LOOP_TERMINALS``, or None when the loop continues.
+    """
+    _ = reviewed_head_count
+    if is_advisor_unreachable and has_unclassified_finding(all_findings):
+        return TERMINAL_ADVISOR_BLOCKED
+    if not all_findings:
+        if is_gates_passed:
+            return TERMINAL_CLEAN
+        return None
+    if (
+        is_nits_only_findings(all_findings)
+        and all_findings_carry_severity_and_verdict(all_findings)
+        and is_nits_applied
+        and is_gates_passed
+    ):
+        return TERMINAL_NITS_FIXED
+    return None
+
+
+def encode_review_loop_terminal_result(
+    *,
+    terminal: str,
+    all_surviving_findings: Sequence[Mapping[str, object]],
+    reviewed_head_count: int,
+    is_draft_preserved: bool,
+) -> dict[str, object]:
+    """Serialize a review-loop terminal for hand-off and reporting.
+
+    ::
+
+        encode_review_loop_terminal_result(
+            terminal="advisor_blocked",
+            all_surviving_findings=[{"severity": "high", "verdict": "CONFIRMED"}],
+            reviewed_head_count=2,
+            is_draft_preserved=False,
+        )["draft_preserved"]  # ok: True  (blocked terminals force draft)
+
+    ``advisor_blocked`` keeps the pull request draft even when the caller
+    passes a false draft flag. Other terminals use the caller's flag.
+    Every terminal uses the same JSON shape.
+
+    Args:
+        terminal: One of ``ALL_LOOP_TERMINALS``.
+        all_surviving_findings: Findings still open at the terminal.
+        reviewed_head_count: Distinct heads reviewed before this terminal.
+        is_draft_preserved: Whether the pull request stays in draft.
+
+    Returns:
+        A JSON-ready mapping with terminal, draft flag, head count, findings.
+    """
+    is_blocked_terminal = terminal == TERMINAL_ADVISOR_BLOCKED
+    should_preserve_draft = is_blocked_terminal or is_draft_preserved
+    return {
+        RESULT_KEY_TERMINAL: terminal,
+        RESULT_KEY_DRAFT_PRESERVED: should_preserve_draft,
+        RESULT_KEY_REVIEWED_HEAD_COUNT: reviewed_head_count,
+        RESULT_KEY_SURVIVING_FINDINGS: list(all_surviving_findings),
+    }

package/scripts/dev_env_scripts_constants/grok_run_ledger_constants.py

@@ -0,0 +1,50 @@
+"""Named constants for the host-neutral Grok run ledger and patch artifacts."""
+
+from __future__ import annotations
+
+LEDGER_SCHEMA_VERSION: str = "1.0.0"
+"""Schema version stamped on every ledger document and task record."""
+
+LEDGER_FILENAME: str = "grok-run-ledger.json"
+"""Default ledger filename under a run-state directory."""
+
+PATCH_MANIFEST_FILENAME: str = "patch-manifest.json"
+"""Default patch-manifest filename under a run-state directory."""
+
+TASK_STATUS_PENDING: str = "pending"
+"""Task is recorded and waiting for dispatch."""
+
+TASK_STATUS_IN_PROGRESS: str = "in_progress"
+"""Task has exactly one live owner and is being worked."""
+
+TASK_STATUS_COMPLETED: str = "completed"
+"""Task reached a successful terminal state."""
+
+TASK_STATUS_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Task stopped because the advisor bind or verdict failed closed."""
+
+TASK_STATUS_PENDING_REVIEW: str = "pending_review"
+"""Task was invalidated by snapshot drift and needs re-review."""
+
+ALL_LEGAL_TASK_STATUSES: frozenset[str] = frozenset(
+    {
+        TASK_STATUS_PENDING,
+        TASK_STATUS_IN_PROGRESS,
+        TASK_STATUS_COMPLETED,
+        TASK_STATUS_ADVISOR_BLOCKED,
+        TASK_STATUS_PENDING_REVIEW,
+    }
+)
+"""Every legal task status the ledger accepts."""
+
+UTF8_ENCODING: str = "utf-8"
+"""Text encoding for ledger and patch-manifest files."""
+
+JSON_INDENT: int = 2
+"""Indent width for pretty-printed ledger and patch-manifest JSON."""
+
+TEMPORARY_LEDGER_PREFIX: str = ".ledger-"
+"""Prefix for atomic ledger temp files before replace."""
+
+TEMPORARY_LEDGER_SUFFIX: str = ".tmp"
+"""Suffix for atomic ledger temp files before replace."""

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -215,8 +215,8 @@ LAUNCH_FAILURE_STDERR_PREFIX: str = "failed to launch: "
 KILL_GRACE_TIMEOUT_SECONDS: int = 10
 """Seconds to wait for a killed process to reap its pipes before giving up on its streams.
 
-Gates the drain that follows a kill. ``PROCESS_TREE_KILL_TIMEOUT_SECONDS``
-gates the kill command itself, so the two bound different operations.
+Gates the drain that follows a kill. The shared process-tree helper carries its
+own bound on the kill command, so the two bound different operations.
 """
 
 MAXIMUM_WORKER_TIMEOUT_SECONDS: int = 5400
@@ -235,28 +235,6 @@ MAXIMUM_WORKER_TIMEOUT_ERROR_TEMPLATE: str = (
 )
 """Rejection message for an over-ceiling timeout, shared by the batch parse and the runner."""
 
-WINDOWS_OS_NAME: str = "nt"
-"""``os.name`` value that selects the Windows branch of the process-tree kill."""
-
-WINDOWS_TASKKILL_COMMAND: str = "taskkill"
-"""Windows command that ends a process by id."""
-
-WINDOWS_TASKKILL_TREE_FLAG: str = "/T"
-"""``taskkill`` flag that extends the kill to every descendant process."""
-
-WINDOWS_TASKKILL_FORCE_FLAG: str = "/F"
-"""``taskkill`` flag that forces termination rather than requesting it."""
-
-WINDOWS_TASKKILL_PID_FLAG: str = "/PID"
-"""``taskkill`` flag that names the target process id."""
-
-PROCESS_TREE_KILL_TIMEOUT_SECONDS: int = 10
-"""Seconds allowed for the tree-kill command itself before it is abandoned.
-
-Gates the kill command. ``KILL_GRACE_TIMEOUT_SECONDS`` gates the drain that
-follows a kill, so the two bound different operations.
-"""
-
 MIN_WORKER_TIMEOUT_SECONDS: int = 1
 """Minimum accepted worker timeout_seconds, in seconds.
 
@@ -396,6 +374,32 @@ WORKER_SPEC_IS_REPO_ONLY_KEY: str = "is_repo_only"
 WORKER_SPEC_AGENT_NAME_KEY: str = "agent_name"
 """JSON key for one worker's optional agent definition name."""
 
+ALL_KNOWN_WORKER_SPEC_KEYS: frozenset[str] = frozenset(
+    {
+        WORKER_SPEC_ROLE_NAME_KEY,
+        WORKER_SPEC_PROMPT_PARTS_KEY,
+        WORKER_SPEC_CWD_KEY,
+        WORKER_SPEC_TOOL_PROFILE_KEY,
+        WORKER_SPEC_TIMEOUT_KEY,
+        WORKER_SPEC_IS_REPO_ONLY_KEY,
+        WORKER_SPEC_AGENT_NAME_KEY,
+    }
+)
+"""Every JSON key a batch worker entry accepts.
+
+A worker entry carrying any other key fails to load, so a key the launcher
+would drop is named to the operator rather than passing for a setting that
+took effect.
+"""
+
+WORKER_SPEC_KEY_JOIN_SEPARATOR: str = ", "
+"""Separator between key names listed in an unknown-worker-key error message."""
+
+UNKNOWN_WORKER_KEY_ERROR_TEMPLATE: str = (
+    "unknown worker key(s): {unknown_keys}; accepted keys: {accepted_keys}"
+)
+"""Message raised when a worker entry carries a key outside the accepted set."""
+
 CLI_BATCH_SPEC_FLAG: str = "--spec"
 """CLI flag that points the batch launcher at a JSON batch specification file."""
 
@@ -499,3 +503,107 @@ CLI_ENABLE_CLAUDE_TIER_FLAG: str = "--enable-claude-tier"
 
 EMPTY_OUTPUT: str = ""
 """Empty captured output when no tier produced stdout."""
+
+BATCH_SPEC_ADVISOR_KEY: str = "advisor"
+"""JSON key for the optional batch-level worker-advisor block."""
+
+ADVISOR_SPEC_LAUNCHER_KEY: str = "launcher"
+"""JSON key for the lead-supplied advisor launcher executable name."""
+
+ADVISOR_SPEC_MODEL_KEY: str = "model"
+"""JSON key for the advisor model name."""
+
+ADVISOR_SPEC_EFFORT_KEY: str = "effort"
+"""JSON key for the advisor effort level."""
+
+DEFAULT_ADVISOR_LAUNCHER_PLACEHOLDER: str = "ADVISOR_LAUNCHER_PLACEHOLDER"
+"""Committed placeholder; real launcher arrives only from the lead's batch spec."""
+
+DEFAULT_ADVISOR_MODEL: str = "opus"
+"""Default advisor model when the batch advisor block omits model."""
+
+DEFAULT_ADVISOR_EFFORT: str = "high"
+"""Default advisor effort when the batch advisor block omits effort."""
+
+MAXIMUM_WORKER_ADVISOR_CORRECTIONS: int = 3
+"""Maximum CORRECTION/PLAN re-consults per worker before advisor_blocked."""
+
+MAXIMUM_ADVISOR_TIMEOUT_SECONDS: int = 600
+"""Timeout for one advisor launcher subprocess call, in seconds."""
+
+ADVISOR_SIGNAL_ENDORSE: str = "ENDORSE"
+"""Opening signal that accepts a worker report."""
+
+ADVISOR_SIGNAL_CORRECTION: str = "CORRECTION"
+"""Opening signal that requires a re-consult up to the correction cap."""
+
+ADVISOR_SIGNAL_PLAN: str = "PLAN"
+"""Opening signal treated like CORRECTION for re-consult counting."""
+
+ADVISOR_SIGNAL_STOP: str = "STOP"
+"""Opening signal that ends the worker as advisor_blocked immediately."""
+
+ALL_KNOWN_ADVISOR_SIGNALS: frozenset[str] = frozenset(
+    {
+        ADVISOR_SIGNAL_ENDORSE,
+        ADVISOR_SIGNAL_CORRECTION,
+        ADVISOR_SIGNAL_PLAN,
+        ADVISOR_SIGNAL_STOP,
+    }
+)
+"""The four allowed first tokens of an advisor reply."""
+
+CLASSIFICATION_ADVISOR_BLOCKED: str = "advisor_blocked"
+"""Worker classification when advisor bind, resume, or verdict fails closed."""
+
+PENDING_BIND_SENTINEL: str = "PENDING_BIND"
+"""Unbound advisor session or signal sentinel; must fail closed before launch."""
+
+ADVISOR_PROMPT_HEADER_TEMPLATE: str = (
+    "Worker advisor session: {session_id}\n"
+    "Advisor model: {model}\n"
+    "Advisor effort: {effort}\n"
+    "Report only after the same session endorses or corrections are applied.\n\n"
+)
+"""Prefix injected into each worker prompt after a successful pre-dispatch bind."""
+
+SUMMARY_ADVISOR_SESSION_ID_KEY: str = "advisor_session_id"
+"""Per-worker report JSON key for the unique advisor session id."""
+
+SUMMARY_ADVISOR_SIGNAL_KEY: str = "advisor_completion_signal"
+"""Per-worker report JSON key for the final advisor opening signal."""
+
+SUMMARY_ADVISOR_LAUNCHER_KEY: str = "advisor_launcher"
+"""Per-worker report JSON key for the spec-supplied launcher (runtime only)."""
+
+ADVISOR_CLI_PRINT_FLAG: str = "-p"
+"""Print/non-interactive flag passed to the advisor launcher."""
+
+ADVISOR_CLI_MODEL_FLAG: str = "--model"
+"""Model flag passed to the advisor launcher."""
+
+ADVISOR_CLI_EFFORT_FLAG: str = "--effort"
+"""Effort flag passed to the advisor launcher."""
+
+ADVISOR_CLI_OUTPUT_FORMAT_FLAG: str = "--output-format"
+"""Output-format flag passed to the advisor launcher."""
+
+ADVISOR_CLI_OUTPUT_FORMAT_JSON: str = "json"
+"""JSON output format value for advisor launcher calls."""
+
+ADVISOR_CLI_RESUME_FLAG: str = "--resume"
+"""Resume flag for post-report advisor consults."""
+
+ADVISOR_BIND_PROMPT_TEMPLATE: str = (
+    "You are the unique worker advisor for role {role_name}. "
+    "Answer only. Open with exactly one of: ENDORSE | CORRECTION | PLAN | STOP. "
+    "Pre-dispatch: ENDORSE this worker assignment if safe, else CORRECTION."
+)
+"""Prompt body used for the pre-dispatch advisor bind."""
+
+ADVISOR_VERDICT_PROMPT_TEMPLATE: str = (
+    "You are the unique worker advisor for role {role_name}, session {session_id}. "
+    "Answer only. Open with exactly one of: ENDORSE | CORRECTION | PLAN | STOP. "
+    "Post-report review of the worker report follows.\n\n{report_text}"
+)
+"""Prompt body used for the post-report advisor verdict."""