feat: add --estimate-time flag and time estimates to pre-run confirmation

- Add THOROUGH_SECONDS_PER_FILE calibration constants to cost.py (python=100s,
  docs=200s, config=150s, generic=120s) from production run data
- Add _classify_file_type() and time_estimate() to cost.py; returns
  TimeEstimate with mid/min/max seconds and recommended --timeout (max+20%)
- Add --estimate-time flag to quorum run: resolves files, prints estimate
  table, exits without validating (no API key required)
- Update _show_cost_estimate_and_confirm() to show time alongside cost:
  'Estimated: ~28 min, ~$0.20 (13 files, thorough) [approximate]'
- 26 new tests covering file classification, time_estimate(), and CLI flag

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Akkari

reference-implementation/quorum/cli.py

@@ -144,6 +144,12 @@ def cli(verbose: bool) -> None:
     default=False,
     help="Generate audit-detail.csv and audit-summary.csv in the run directory. Auto-enabled at --depth thorough.",
 )
+@click.option(
+    "--estimate-time",
+    is_flag=True,
+    default=False,
+    help="Show a time estimate for the run (files, duration, recommended --timeout) then exit without validating.",
+)
 def run_cmd(
     target: str | None,
     pattern: str | None,
@@ -159,6 +165,7 @@ def run_cmd(
     max_cost: float | None,
     yes: bool,
     audit_report: bool,
+    estimate_time: bool,
 ) -> None:
     """
     Validate artifacts against a rubric.
@@ -189,8 +196,8 @@ def run_cmd(
         print_error("Provide --target <path> to start a new run, or --resume <batch-dir> to continue an interrupted one.")
         sys.exit(1)
 
-    # Check for API keys before doing any work
-    if not _has_api_key():
+    # Check for API keys before doing any work (skip for --estimate-time, no LLM needed)
+    if not estimate_time and not _has_api_key():
         _first_run_setup()
         if not _has_api_key():
             print_error(
@@ -256,6 +263,15 @@ def run_cmd(
             or "?" in target
         )
 
+        # --estimate-time: resolve files, print estimate table, exit without validating
+        if estimate_time:
+            if is_batch:
+                files = resolve_targets(target, pattern)
+            else:
+                files = [target_path]
+            _show_time_estimate(files, depth, quorum_config)
+            sys.exit(0)
+
         # Auto-enable audit report at thorough depth
         effective_audit = audit_report or (depth == "thorough")
 
@@ -642,30 +658,61 @@ def _first_run_setup(force: bool = False) -> None:
     click.echo()
 
 
+def _format_duration(seconds: int) -> str:
+    """Format a duration in seconds to a human-readable string."""
+    if seconds <= 0:
+        return "0 sec"
+    if seconds < 60:
+        return f"{seconds} sec"
+    mins = round(seconds / 60)
+    return f"{mins} min"
+
+
+def _show_time_estimate(files: list, depth: str, config: object) -> None:
+    """Print a time estimate table for --estimate-time and exit."""
+    from quorum.cost import time_estimate, estimate_cost
+
+    te = time_estimate(files, depth)
+    ce = estimate_cost(files, config)
+
+    click.echo()
+    click.echo(f"  Files to validate:     {te.files_count}")
+    click.echo(
+        f"  Estimated duration:    ~{_format_duration(te.estimated_seconds)} "
+        f"(range: {_format_duration(te.min_seconds)}\u2013{_format_duration(te.max_seconds)})"
+    )
+    click.echo(f"  Estimated cost:        ~${ce.estimated_usd:.2f} [approximate]")
+    if te.recommended_timeout > 0:
+        click.echo(f"  Recommended --timeout: {te.recommended_timeout} seconds (max + 20% buffer)")
+    click.echo()
+
+
 def _show_cost_estimate_and_confirm(
     files: list,
     config: object,
     skip_prompt: bool,
 ) -> None:
     """
-    Show a pre-run cost estimate and optionally prompt to continue.
+    Show a pre-run cost + time estimate and optionally prompt to continue.
 
     Skips the prompt when:
     - --yes flag is set
     - estimate is below $0.50 (low-cost run, no need to interrupt)
     - not running in an interactive terminal
     """
     try:
-        from quorum.cost import estimate_cost
-        estimate = estimate_cost(files, config)
+        from quorum.cost import estimate_cost, time_estimate
+        ce = estimate_cost(files, config)
+        te = time_estimate(files, getattr(config, "depth_profile", "standard"))
         click.echo(
-            f"Estimated cost: ~${estimate.estimated_usd:.2f} "
-            f"({estimate.estimated_calls} critic calls across {estimate.files_count} files) "
+            f"Estimated: ~{_format_duration(te.estimated_seconds)}, "
+            f"~${ce.estimated_usd:.2f} "
+            f"({ce.files_count} files, {getattr(config, 'depth_profile', '?')}) "
             f"[approximate]",
             err=True,
         )
 
-        if skip_prompt or estimate.estimated_usd < 0.50 or not sys.stdin.isatty():
+        if skip_prompt or ce.estimated_usd < 0.50 or not sys.stdin.isatty():
             return
 
         if not click.confirm("Proceed with validation?", default=True):

reference-implementation/quorum/cost.py

@@ -20,7 +20,33 @@
 
 logger = logging.getLogger(__name__)
 
-# Approximate per-token costs (USD) for common models.
+# ── Time estimation calibration constants ────────────────────────────────────
+
+# Thorough depth: per-file time in seconds by file type.
+# Multipliers relative to python baseline (1.0x): docs=2.0x, config=1.5x, generic=1.2x
+# Source: production runs (13 Python files → ~22 min observed; docs heavier due to critic work)
+THOROUGH_SECONDS_PER_FILE: dict[str, int] = {
+    "python": 100,   # observed: ~100 sec/file
+    "docs": 200,     # observed range: 180-240 sec/file
+    "config": 150,   # 1.5x python baseline
+    "generic": 120,  # 1.2x python baseline
+}
+
+# Calibrated ranges for thorough depth per file type: (min_sec, max_sec)
+_THOROUGH_RANGE: dict[str, tuple[int, int]] = {
+    "python": (85, 115),
+    "docs": (180, 240),
+    "config": (128, 172),
+    "generic": (102, 138),
+}
+
+# Quick/standard depth: (min_sec, mid_sec, max_sec) — same for all file types
+_DEPTH_SECONDS: dict[str, tuple[int, int, int]] = {
+    "quick": (10, 12, 15),      # pre-screen only, no LLM calls
+    "standard": (45, 52, 60),
+}
+
+# ── Approximate per-token costs (USD) for common models ──────────────────────
 # Format: {model_name_fragment: (input_per_1k_tokens, output_per_1k_tokens)}
 # Check your provider's current pricing — these are approximate.
 _MODEL_RATES: dict[str, tuple[float, float]] = {
@@ -93,6 +119,18 @@ class CostEstimate(BaseModel):
     is_approximate: bool = True
 
 
+class TimeEstimate(BaseModel):
+    """Pre-run time estimate for a validation run."""
+
+    depth: str
+    files_count: int
+    estimated_seconds: int
+    min_seconds: int
+    max_seconds: int
+    recommended_timeout: int  # max_seconds * 1.2, gives a 20% buffer
+    per_type_counts: dict[str, int] = Field(default_factory=dict)
+
+
 class CostTracker:
     """
     Thread-safe tracker for LLM token usage and cost.
@@ -261,3 +299,60 @@ def estimate_cost(files: list[Path], config: Any) -> CostEstimate:
         critics_count=num_critics,
         is_approximate=True,
     )
+
+
+def _classify_file_type(path: Path) -> str:
+    """Classify a file path into a time-estimation category."""
+    suffix = path.suffix.lower()
+    if suffix in {".py", ".pyx", ".pyi"}:
+        return "python"
+    if suffix in {".md", ".rst", ".txt"}:
+        return "docs"
+    if suffix in {".yaml", ".yml", ".json", ".toml"}:
+        return "config"
+    return "generic"
+
+
+def time_estimate(files: list[Path], depth: str) -> TimeEstimate:
+    """
+    Estimate wall-clock time for a Quorum validation run.
+
+    Uses calibration data from production runs:
+    - quick:    ~10-15 sec/file (pre-screen only, no LLM)
+    - standard: ~45-60 sec/file
+    - thorough: ~85-240 sec/file depending on file type
+
+    Args:
+        files: List of file paths to validate.
+        depth: Depth profile — "quick", "standard", or "thorough".
+
+    Returns:
+        TimeEstimate with mid/min/max seconds and recommended --timeout.
+    """
+    depth_lower = depth.lower()
+    per_type: dict[str, int] = {}
+    total_min = total_mid = total_max = 0
+
+    for f in files:
+        ftype = _classify_file_type(f)
+        per_type[ftype] = per_type.get(ftype, 0) + 1
+
+        if depth_lower == "thorough":
+            mid = THOROUGH_SECONDS_PER_FILE[ftype]
+            mn, mx = _THOROUGH_RANGE[ftype]
+        else:
+            mn, mid, mx = _DEPTH_SECONDS.get(depth_lower, _DEPTH_SECONDS["standard"])
+
+        total_min += mn
+        total_mid += mid
+        total_max += mx
+
+    return TimeEstimate(
+        depth=depth_lower,
+        files_count=len(files),
+        estimated_seconds=total_mid,
+        min_seconds=total_min,
+        max_seconds=total_max,
+        recommended_timeout=int(total_max * 1.2),
+        per_type_counts=per_type,
+    )