| name | verification-recipe-runner |
| description | Run WHENEVER you are about to open a PR (or push to a shared branch) in this repo after changing code, tools, artifacts, or docs — and whenever you say "let me push this", "open a PR", "it's ready", "fix the failing check", or "wrap up this change". It is the standard per-agent shape before a PR: localize the change, repair, validate the behavior, run the ci-artifact-drift gates + `make claim-check`, resolve review threads for real, and push ONLY gate-green. Sequences this repo's existing deterministic tools so the PR lands green the first time instead of red on drift, an overclaim, or an unresolved thread. Fires even for a "one-line" change — the cheap gates are what keep this high-churn repo landable.
|
| metadata | {"short-description":"The localize→repair→validate→gate→resolve→push-green recipe before any PR here"} |
verification-recipe-runner
The fixed shape every agent runs before opening a PR in this repo. It does not invent new
checks — it sequences the deterministic tools that already exist (git-discipline,
ci-artifact-drift, session-handover, spark-cluster-ops) into one repeatable recipe so a PR
lands green on the first try. This is dev-workflow tooling: it makes ZERO capability claim;
canClaimAGI stays false; every gate is honest-or-NO-GO and no threshold is ever lowered to pass.
Almost every red PR here is not a real bug — it is (a) a generated artifact that drifted,
(b) a no-overclaim gate tripping, (c) an unresolved review thread silently blocking, or
(d) a fix built on a stale local checkout. This recipe closes all four before you push.
0. Situate — you are on a STALE snapshot (read-only, ~1 s)
Work in your OWN throwaway worktree off origin/main; never touch the shared primary tree.
git fetch origin --prune
python .agents/skills/git-operations/scripts/git_situational_awareness.py
Confirm the problem you are fixing is still broken on fresh origin/main (another advisor may
have fixed it) and that no competing PR already exists. Full rules: git-discipline. Cluster
worktree/git-crypt -c bypass + collision recovery: spark-cluster-ops §3.
1. Localize
Pin the change to the smallest set of files and reproduce the failure/behavior FIRST, on the
current head, before editing. If it's a CI red, read the actual job conclusion — a failure
may really be a cancelled run (main moved mid-run), not a bug (git-discipline §3).
2. Repair
Make the minimal fix. If the change is capability/measurement-shaped (a number, a status,
"validated", a RESULTS.md/gate entry) stop — that is the no-overclaim contract, not mechanics;
escalate per ci-artifact-drift / sophia-agi. Never edit a generated file by hand (§4).
3. Validate the behavior (not just "it compiles")
Drive the affected surface end-to-end and observe it — for a tool, actually run it; for a fix,
reproduce-then-confirm-gone. Syntax floor:
python -m compileall -q agent okf tools agi-proof 2>/dev/null
GPU-touching validation is subject to the one-GPU-job invariant: route heavy Spark work THROUGH
the bridge poller, or nvidia-smi headroom-check before any direct tmux/ollama launch — a stray
load silently KILLS an in-flight cert/train (spark-cluster-ops §2). Announce long runs in
SESSION-COORDINATION.md (the live, untracked CLAIM/OWNS/DONE ledger) so peers don't double-launch,
and surface elapsed+ETA+progress via TrainWatch (spark-2f2d:8420) / the cluster dashboard for
any train/bench/judge run — never report a bare final number.
4. Run the gates (the whole reason PRs go red here)
The measurement contract + generated-artifact drift are BOTH deterministic and local. Run the
ci-artifact-drift sweep so CI is green first try:
make claim-check
python tools/build_results_page.py --check && \
python tools/wiki_sync.py check && \
python tools/build_rag_index.py --verify && \
python tools/build_local_sophia_dataset.py --check && \
python tools/check_version_consistency.py && \
python tools/validate_failure_ledger.py --check && echo "ARTIFACTS CLEAN"
If a --check/--verify fails, regenerate ONLY the artifact you touched (see the
ci-artifact-drift table), re-run the check, then proceed. If a gate flips to NO-GO, that is a
REAL result — label it candidate and add an agi-proof/failure-ledger.md entry; never lower a
threshold to force a pass. Never stage agi-proof/benchmark-results/rlvr.public-report.json,
.venv/, or training/rlvr/checkpoints/ (spark-cluster-ops §4).
The required CI checks are fast + ci-complete; both must be green for main-protection.
5. Commit isolated + open the PR
The shared tree is often dirty with other agents' WIP. Stage an explicit file list only:
git add <explicit paths>
git diff --cached --stat
git commit -m "…"
git push --force-with-lease
PR body per prompt-author: state how "done" is verified, bound the scope, make no overclaim.
6. Resolve review threads FOR REAL — the silent blocker
main-protection sets required_review_thread_resolution: true: green checks but ANY unresolved
thread still blocks the merge. Address each comment with a real fix or a real reply, then resolve it
(don't resolve-to-silence). Enumerate every blocker — not just CI:
python .agents/skills/multi-agent-merge-preflight/scripts/merge_blockers.py <NNN>
Thread-resolution gh api graphql recipe: .agents/skills/pr-merge-verification/SKILL.md.
7. Push / merge ONLY gate-green
Merge only when §4 is clean AND every thread is resolved. Two-phase (spark-cluster-ops §6):
gh pr merge <N> --squash --auto --delete-branch; if it stalls on the thread gate once checks are
green, --squash --admin --delete-branch. Always --squash (linear history).
Recipe, one line
fetch → localize → repair → validate (one-GPU-safe) → make claim-check + drift sweep →
commit explicit → resolve threads for real → merge green. Skip a step and the PR goes red on
drift, an overclaim, a stale base, or an unresolved thread — exactly the four this recipe removes.
