feat: add staging → official run promotion workflow

LoCoBench Bot · claude · LoCoBench Bot · commit df67d0ade9d7 · 2026-02-17T00:24:49.000Z
Runs now land in runs/staging/ by default instead of runs/official/.
After validation, use promote_run.py to move to official.

- New scripts/promote_run.py: --list, --execute, --force, --all flags
  Validates flagged_tasks.json (0 criticals gate), checks all tasks
  have result.json, moves to official, regenerates MANIFEST
- Update all 34 config scripts: CATEGORY default official → staging
- aggregate_status.py: add --staging flag to scan staging runs
- check_infra.py: add staging_dir check
- CLAUDE.md: document promotion workflow and promote_run.py

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -29,6 +29,7 @@ scripts/
   cost_report.py             # Token/cost aggregation
   sync_task_metadata.py      # task.toml vs selection registry reconciliation
   archive_run.py             # Archive old runs to save disk
+  promote_run.py             # Validate & promote staging runs to official
   rerun_failed.py            # Generate rerun commands for failed tasks
 
 docs/
@@ -64,15 +65,23 @@ docs/
 
 ## Running Tasks
 
+Runs land in `runs/staging/` by default. After validation, promote to `runs/official/`.
+
 ```bash
-# Run a single benchmark (2 configs: baseline, SG_full)
+# Run a benchmark (lands in runs/staging/)
 ./configs/pytorch_2config.sh
 
 # Run with parallel execution
 ./configs/pytorch_2config.sh --parallel
 
-# Override parallelism
-./configs/pytorch_2config.sh --parallel 4
+# Check staging runs
+python3 scripts/promote_run.py --list
+
+# Promote validated run to official
+python3 scripts/promote_run.py --execute pytorch_opus_20260217_120000
+
+# Skip staging (write directly to official)
+CATEGORY=official ./configs/pytorch_2config.sh
 ```
 
 See [AGENTS.md](AGENTS.md) for parallel execution details and multi-account setup.
@@ -111,6 +120,13 @@ python3 scripts/generate_eval_report.py
 
 # Select benchmark tasks
 python3 scripts/select_benchmark_tasks.py
+
+# Promote staging runs to official
+python3 scripts/promote_run.py --list                    # View staging runs
+python3 scripts/promote_run.py --execute <run_name>      # Promote to official
+
+# Monitor staging runs
+python3 scripts/aggregate_status.py --staging
 ```
 
 ## Operational Skills (17)
@@ -180,6 +196,7 @@ MAINTENANCE
 |-------|--------|---------|
 | `/sync-metadata` | `scripts/sync_task_metadata.py` | Reconcile task.toml vs selected_benchmark_tasks.json, `--fix` to auto-update |
 | `/archive-run` | `scripts/archive_run.py` | Move old runs to archive/, optional compression, dry-run by default |
+| `/promote-run` | `scripts/promote_run.py` | Validate and promote staging runs to official, regenerate MANIFEST |
 | `/reextract-metrics` | `scripts/reextract_all_metrics.py` | Batch re-extract task_metrics.json after extraction bug fixes or schema changes |
 
 ### Supporting Scripts
diff --git a/configs/archive/repoqa_2config.sh b/configs/archive/repoqa_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/codereview_2config.sh b/configs/codereview_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/crossrepo_2config.sh b/configs/crossrepo_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/dehinted_rerun_2config.sh b/configs/dehinted_rerun_2config.sh
@@ -55,7 +55,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/dependeval_2config.sh b/configs/dependeval_2config.sh
@@ -66,7 +66,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/dibench_2config.sh b/configs/dibench_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/docgen_2config.sh b/configs/docgen_2config.sh
@@ -65,7 +65,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 TASK_FILTER=""
 
 # All docgen task IDs — populated by task-creation Ralphs
diff --git a/configs/enterprise_2config.sh b/configs/enterprise_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/gapfill_all.sh b/configs/gapfill_all.sh
@@ -42,7 +42,7 @@ AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 SELECTION_FILE="$SCRIPT_DIR/selected_benchmark_tasks.json"
 
 RUN_PYTORCH=true
diff --git a/configs/gapfill_remaining.sh b/configs/gapfill_remaining.sh
@@ -41,7 +41,7 @@ AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 RUN_PYTORCH=true
 RUN_SWEBENCHPRO=true
 DRY_RUN=false
diff --git a/configs/gapfill_targeted.sh b/configs/gapfill_targeted.sh
@@ -62,7 +62,7 @@ AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 SUITE=""
 CONFIG=""
 DRY_RUN=false
diff --git a/configs/governance_2config.sh b/configs/governance_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/investigation_2config.sh b/configs/investigation_2config.sh
@@ -65,7 +65,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 TASK_FILTER=""
 
 # All investigation task IDS
diff --git a/configs/isolated_k8sdocs_2config.sh b/configs/isolated_k8sdocs_2config.sh
@@ -65,7 +65,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=3
 RUN_ISOLATED=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/k8s_docs_2config.sh b/configs/k8s_docs_2config.sh
@@ -64,7 +64,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER="${TIMEOUT_MULTIPLIER:-3}"  # 3x default for 900s task timeout
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/largerepo_2config.sh b/configs/largerepo_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=1  # Big codebases - run serially within each task
 TIMEOUT_MULTIPLIER=10  # 10x default timeout for large repos
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/largerepo_sg_compare.sh b/configs/largerepo_sg_compare.sh
@@ -59,7 +59,7 @@ AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 CONCURRENCY=1
 TIMEOUT_MULTIPLIER=10
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 RUN_LATEST=true
 RUN_PRECISE=true
 
diff --git a/configs/linuxflbench_2config.sh b/configs/linuxflbench_2config.sh
@@ -71,7 +71,7 @@ CONCURRENCY=1
 TIMEOUT_MULTIPLIER="${TIMEOUT_MULTIPLIER:-10}"
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/locobench_2config.sh b/configs/locobench_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/navprove_2config.sh b/configs/navprove_2config.sh
@@ -65,7 +65,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 TASK_FILTER=""
 
 # All navprove task IDs
diff --git a/configs/nlqa_2config.sh b/configs/nlqa_2config.sh
@@ -65,7 +65,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 TASK_FILTER=""
 
 # All nlqa task IDs — populated by task-creation Ralphs
diff --git a/configs/onboarding_2config.sh b/configs/onboarding_2config.sh
@@ -65,7 +65,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 TASK_FILTER=""
 
 # All onboarding task IDs — populated by task-creation Ralphs
diff --git a/configs/pytorch_2config.sh b/configs/pytorch_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/rerun_remaining.sh b/configs/rerun_remaining.sh
@@ -58,7 +58,7 @@ AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 SELECTION_FILE="$SCRIPT_DIR/selected_benchmark_tasks.json"
 
 # Disable fail-fast so one suite's failure doesn't block others
diff --git a/configs/run_selected_tasks.sh b/configs/run_selected_tasks.sh
@@ -53,7 +53,7 @@ TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_BASE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 DRY_RUN=false
 SKIP_COMPLETED=false
 AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
diff --git a/configs/security_2config.sh b/configs/security_2config.sh
@@ -65,7 +65,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 TASK_FILTER=""
 
 # All security task IDs — populated by task-creation Ralphs
diff --git a/configs/sgonly_build_2config.sh b/configs/sgonly_build_2config.sh
@@ -71,7 +71,7 @@ TIMEOUT_MULTIPLIER=10
 RUN_SGONLY=true
 RUN_FULL=true
 SUITE_FILTER=""
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 while [[ $# -gt 0 ]]; do
     case $1 in
diff --git a/configs/sgonly_writeonly_2config.sh b/configs/sgonly_writeonly_2config.sh
@@ -69,7 +69,7 @@ TIMEOUT_MULTIPLIER=3
 RUN_SGONLY=true
 RUN_FULL=true
 SUITE_FILTER=""
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/swebenchpro_2config.sh b/configs/swebenchpro_2config.sh
@@ -64,7 +64,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER="${TIMEOUT_MULTIPLIER:-10}"
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/swebenchpro_gapfill.sh b/configs/swebenchpro_gapfill.sh
@@ -28,7 +28,7 @@ AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 RUN_BASELINE=true
 RUN_BASE=true
 RUN_FULL=true
diff --git a/configs/swebenchpro_rerun_infra_failures.sh b/configs/swebenchpro_rerun_infra_failures.sh
@@ -44,7 +44,7 @@ AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 DRY_RUN=false
 RUN_BASELINE=true
 RUN_BASE=true
diff --git a/configs/sweperf_2config.sh b/configs/sweperf_2config.sh
@@ -63,7 +63,7 @@ CONCURRENCY=2
 TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/tac_2config.sh b/configs/tac_2config.sh
@@ -107,7 +107,7 @@ TIMEOUT_MULTIPLIER=10
 RUN_BASELINE=true
 RUN_FULL=true
 SKIP_SERVER_CHECK=false
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
diff --git a/configs/universal_paired_rerun.sh b/configs/universal_paired_rerun.sh
@@ -56,7 +56,7 @@ MODEL="${MODEL:-anthropic/claude-opus-4-6}"
 AGENT_PATH="agents.claude_baseline_agent:BaselineClaudeCodeAgent"
 TIMEOUT_MULTIPLIER=10
 CONCURRENCY=1          # Trials per task (1 = single attempt)
-CATEGORY="${CATEGORY:-official}"
+CATEGORY="${CATEGORY:-staging}"
 BENCHMARK_FILTER=""    # Empty = all benchmarks
 ONLY_TASKS=""          # Empty = all tasks; space-separated list = only these
 DRY_RUN=false
diff --git a/scripts/aggregate_status.py b/scripts/aggregate_status.py
@@ -42,7 +42,9 @@
 # Constants (duplicated from generate_manifest.py for independence)
 # ---------------------------------------------------------------------------
 
-RUNS_DIR = Path(__file__).resolve().parent.parent / "runs" / "official"
+RUNS_DIR_OFFICIAL = Path(__file__).resolve().parent.parent / "runs" / "official"
+RUNS_DIR_STAGING = Path(__file__).resolve().parent.parent / "runs" / "staging"
+RUNS_DIR = RUNS_DIR_OFFICIAL  # default; overridden by --staging flag
 
 # __v1_hinted: old run dirs from before enterprise task de-hinting (US-001..US-003).
 # Appended to batch dir names after reruns complete so pre-redesign data is excluded.
@@ -650,6 +652,10 @@ def parse_args():
         "--interval", type=int, default=60,
         help="Seconds between scans in --watch mode (default: 60)",
     )
+    parser.add_argument(
+        "--staging", action="store_true",
+        help="Scan runs/staging/ instead of runs/official/",
+    )
     return parser.parse_args()
 
 
@@ -671,8 +677,12 @@ def run_once(args) -> dict:
 
 
 def main():
+    global RUNS_DIR
     args = parse_args()
 
+    if args.staging:
+        RUNS_DIR = RUNS_DIR_STAGING
+
     if args.watch:
         try:
             while True:
diff --git a/scripts/check_infra.py b/scripts/check_infra.py
diff --git a/scripts/promote_run.py b/scripts/promote_run.py
