dsh-aris-panel 0.1.0

package/skills/skills-codex/shared-references/effort-contract.md

@@ -0,0 +1,143 @@
+# Effort Contract
+
+## Overview
+
+Every ARIS skill accepts an optional `effort` parameter that controls how much work the system does. This affects breadth, depth, iterations, and coverage — but **never** the quality of cross-model review.
+
+> Design stance: the unattended *procedure* (gather → reason → act → verify → repeat) is the engineered artifact, not any single prompt — after Karpathy's "write the loop, not the prompt" (LOOPS.md, *Field Notes on Agents That Run for Days*).
+
+```
+/any-skill "args" — effort: lite | balanced | max | beast
+```
+
+Default: `balanced` (current behavior, zero change for existing users).
+
+## Hard Invariants (NEVER changed by effort)
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| Codex reasoning_effort | **≥ xhigh** (deep-audit skills run `ultra` — tier table in `reviewer-routing.md`) | Reviewer quality is non-negotiable. `effort` never moves the reviewer tier in either direction — and ARIS `— effort: max` is NOT Codex `reasoning_effort: max` (different axes: pipeline workload vs reviewer reasoning depth) |
+| DBLP/CrossRef citations | **on** | Citation integrity is non-negotiable |
+| Reviewer independence | **on** | Cross-model protocol is non-negotiable |
+| Experiment integrity | **on** | Fraud prevention is non-negotiable |
+| Sanity check | **on** | Safety is non-negotiable |
+| AUTO_PROCEED | **user decides** | Orthogonal to effort |
+| difficulty | **user decides** | Orthogonal to effort |
+
+## Four Levels
+
+### `lite` (~0.4x tokens)
+For budget-constrained users or quick explorations. Minimum viable depth.
+
+### `balanced` (1x tokens) — DEFAULT
+Current ARIS behavior. What existing users get today. No change.
+
+### `max` (~2.5x tokens)
+Go deeper than defaults. More papers, more ideas, more rounds, more detail.
+
+### `beast` (~5-8x tokens)
+No budget limit. Every knob to maximum. For top-venue submission sprints.
+
+## Per-Skill Profiles
+
+### Discovery & Planning
+
+| Skill | Dimension | lite | balanced | max | beast |
+|-------|-----------|------|----------|-----|-------|
+| research-lit | papers found | 6-8 | 10-15 | 18-25 | 40-50 |
+| research-lit | query variants | 2 | 5 | 8 | 15+ |
+| research-lit | deep reads | 3 | 5-8 | 8 | 15+ |
+| idea-creator | ideas generated | 4-6 | 8-12 | 12-16 | 20-30 |
+| idea-creator | pilots | 1-2 | 2-3 | 3-4 | 5-6 |
+| novelty-check | claims checked | 2-3 | 3-4 | 4-6 | all |
+| novelty-check | closest works | top-3 | top-5 | top-8 | top-10+ |
+| research-refine | max rounds | 3 | 5 | 7 | 10+ |
+| research-refine | papers considered | 8 | 15 | 24 | 30+ |
+| experiment-plan | core experiments | 3 | 5 | 7 | 10+ |
+| experiment-plan | seeds | 1 | 3 | 5 | 5 |
+| experiment-plan | baseline families | 2 | 3 | 4 | 5+ |
+
+### Execution
+
+| Skill | Dimension | lite | balanced | max | beast |
+|-------|-----------|------|----------|-----|-------|
+| experiment-bridge | scope | sanity + main | main + basic ablation | + top ablation + robustness | full suite + cross-validation |
+| run-experiment | launches | smoke + main | smoke + multi-seed | + dry run + manifest | full config + multi-GPU parallel |
+| monitor-experiment | depth | latest log | log + JSON | + W&B + anomaly | real-time + auto-alert + trend |
+| analyze-results | findings | 3 | 5 | 8 | full-dimensional + stat tests |
+| ablation-planner | ablations | 2-3 | 4-5 | 6-8 | 10+ |
+
+### Review
+
+| Skill | Dimension | lite | balanced | max | beast |
+|-------|-----------|------|----------|-----|-------|
+| auto-review-loop | max rounds | 2 | 3-4 | 6 | 8+ (until converged) |
+| auto-review-loop | fixes per round | 1-2 | 3-4 | 4-6 | all actionable |
+| research-review | passes | 1 | 1 + follow-up | 1 + 2 follow-ups | 2 independent + cross-compare |
+| experiment-audit | depth | skip | basic 4 checks | full 6 checks | line-by-line + reproduce |
+
+### Writing & Rebuttal
+
+| Skill | Dimension | lite | balanced | max | beast |
+|-------|-----------|------|----------|-----|-------|
+| paper-plan | outline reviews | 0 | 1 | 2 | 3 |
+| paper-plan | citations/section | 2-3 | 4-5 | 5-8 | 8+ |
+| paper-figure | caption reviews | 1 | 1 | 2 | 3 |
+| paper-write | abstract variants | 1 | 1 | 2 | 3 |
+| paper-write | related work depth | shallow | standard | deep | exhaustive |
+| paper-compile | fix attempts | 2 | 3 | 4 | until zero warnings |
+| auto-paper-improvement | rounds | 1 | 2 | 3 | 5 |
+| paper-illustration | render iterations | 2 | 3 | 5 | 7 |
+| rebuttal | draft rounds | 1 | 2 | 3 | 5 |
+| rebuttal | stress tests | 0-1 | 1 | 2 | 3 |
+
+## How to Read Effort in a Skill
+
+Add this to the Constants section of each skill:
+
+```markdown
+## Constants
+
+- **EFFORT = `balanced`** — Work intensity. Options: `lite`, `balanced`, `max`, `beast`. Override: `— effort: max`
+```
+
+Then adjust numeric constants based on effort level. Example:
+
+```
+Parse $ARGUMENTS for `— effort:` directive.
+If not specified, default to `balanced`.
+
+Adjust constants:
+  if effort == "lite":     MAX_PAPERS = 8,  MAX_IDEAS = 6,  MAX_ROUNDS = 2
+  if effort == "balanced": MAX_PAPERS = 15, MAX_IDEAS = 12, MAX_ROUNDS = 4
+  if effort == "max":      MAX_PAPERS = 25, MAX_IDEAS = 16, MAX_ROUNDS = 6
+  if effort == "beast":    MAX_PAPERS = 50, MAX_IDEAS = 30, MAX_ROUNDS = 8
+```
+
+## Transparency
+
+Every skill should print its effort configuration at the start:
+
+```
+⚡ [effort: max] papers=25, ideas=16, rounds=6 | Codex: tier per reviewer-routing.md (floor xhigh)
+```
+
+## Precedence
+
+```
+explicit concrete knob (e.g., review_rounds: 2)
+  > explicit dimension override
+    > overall effort level
+      > skill default (balanced)
+```
+
+Example: `— effort: beast, review_rounds: 3` → everything beast except review capped at 3.
+
+## Token Cost Estimation
+
+| Level | LLM tokens | GPU/wall-clock | Best for |
+|-------|-----------|----------------|----------|
+| lite | ~0.4x | ~0.5x | Quick exploration, budget users |
+| balanced | 1x | 1x | Normal research workflow |
+| max | ~2.5x | ~2x | Serious submission prep |
+| beast | ~5-8x | ~3-4x | Top-venue final sprint |

package/skills/skills-codex/shared-references/evidence-precheck.md

@@ -0,0 +1,73 @@
+# Evidence Pre-check
+
+> **Codex mirror adaptation (normative).** Resolve `evidence_check.py` through
+> `.aris/installed-skills-codex.txt` and `$ARIS_REPO/tools/`. The deterministic
+> existence check may be accepted; the fresh Codex semantic review that follows
+> is same-family and therefore provisional. Only a Claude/Gemini overlay or a
+> deterministic verifier supplies accepted assurance.
+
+ARIS's claim audits (`/result-to-claim`, `/experiment-audit`, `/paper-claim-audit`)
+spend a semantic reviewer call to judge whether a claim is supported. In the base
+Codex mirror that call is same-family/provisional; an overlay or deterministic
+verifier is required for accepted assurance. The
+cheapest, most common integrity failure is *hallucinated evidence*: a claim cites
+a number + a source file, and the file doesn't exist or the number isn't in it.
+You should not need a model call to catch that.
+
+## Two stages — and `verified` ≠ `correct`
+
+```
+stage 1  tools/evidence_check.py   deterministic · no model · fail-closed
+         catches HALLUCINATION — cited path missing, or cited value not in source.
+stage 2  semantic review           fresh Codex (provisional) / overlay or deterministic (accepted)
+         catches WRONG-BUT-REAL — the number IS in the file, but it doesn't
+         support the claim.
+```
+
+A `verified` from stage 1 means **only that the cited evidence exists** — never
+that the claim holds. Existence is execution-completeness (deterministic / safe
+same-model); *support* is a quality verdict that stays with the recorded reviewer
+route (`acceptance-gate.md`: the pre-check DRIVES a gate, it cannot ACQUIT a claim).
+This is the reconcile pattern — a model's self-report cross-checked against
+mechanical ground-truth (adapted from Hermes's curator reconcile-classifier),
+made into a cheap pre-gate that catches hallucination *before* the jury runs and
+spares the codex call on fabricated evidence.
+
+## Conservative by design
+
+The pre-check favors **false-negative over false-positive**: when in doubt it
+returns not-verified and lets the jury decide — it must never emit a false
+`verified`. A pure number is matched by **numeric-token equality** (so `73.2`
+matches `73.20` but `73` does NOT match `73.5`); a non-numeric value by
+normalized substring.
+
+## Where ARIS uses it
+
+- **`/result-to-claim`** Step 1.5: parse each claim's cited `(value, source)`,
+  run the batch pre-check, and **before the codex judgment** mark any claim whose
+  evidence is `path_missing` / `value_not_found` as **unsupported — evidence not
+  found**, and pass the per-claim pre-check status into the codex prompt so the
+  jury sees which claims have verified vs hallucinated evidence.
+- **To extend:** `/experiment-audit` (the "phantom results" check is exactly
+  this) and `/paper-claim-audit` (every reported number → its result file).
+
+## API / CLI
+
+```
+from evidence_check import check_claim, check_batch
+check_claim(value, source, root=".")   # -> {status: verified|path_missing|value_not_found, ...}
+check_batch([{value, source, id?}, ...], root)  # -> {results:[...], summary:{status: n}}
+```
+```
+python3 tools/evidence_check.py <root> --value 73.2 --source results/eval.json   # exit 0 verified
+python3 tools/evidence_check.py <root> --batch claims.json   # exit 1 if any claim hallucinated
+```
+
+## Cross-references
+- `acceptance-gate.md` — the pre-check is the deterministic DRIVE; the jury is the
+  ACQUIT. `verified` is existence (execution-completeness), not correctness.
+- `reviewer-independence.md` — the jury still reads the artifacts itself; the
+  pre-check only flags which claims have evidence to read, never pre-digests the
+  verdict.
+- `experiment-integrity.md` — fabricated/phantom results are exactly what stage 1
+  catches deterministically before stage 2.

package/skills/skills-codex/shared-references/experiment-integrity.md

@@ -0,0 +1,49 @@
+# Experiment Integrity Protocol
+
+## Core Principle
+
+**The model that writes experiment code must NOT be the model that judges experiment integrity.** This is the same principle as reviewer-independence, applied to experiments.
+
+## Prohibited Patterns
+
+### 1. Fake Ground Truth
+- ❌ Creating synthetic "reference" from model outputs and comparing against it
+- ❌ Using baseline model outputs as ground truth
+- ❌ Generating pseudo-GT that is structurally similar to predictions
+- ✅ Using dataset-provided ground truth
+- ✅ Using official evaluation scripts when available
+- ✅ Proxy evaluation is allowed IF explicitly labeled as `synthetic_proxy`
+
+### 2. Score Normalization Fraud
+- ❌ Dividing metrics by max/min of model's own output to get 0.99+
+- ❌ Rescaling scores to hide poor performance
+- ✅ Standard normalization (e.g., min-max across ALL methods including baselines)
+- ✅ Reporting raw and normalized scores side by side
+
+### 3. Phantom Results
+- ❌ Claiming results from files that don't exist
+- ❌ Referencing metrics from functions that are never called
+- ❌ Reporting TRACKER status as DONE when it's still TODO
+- ✅ Every claimed number must trace to an actual output file
+
+### 4. Insufficient Scope
+- ❌ Reporting 2-scene pilot as "comprehensive evaluation"
+- ❌ Using words like "robust", "extensive", "across settings" for tiny experiments
+- ✅ Honestly label scope: "pilot (N=2)", "preliminary", "limited evaluation"
+- ✅ State exact scope: N scenes, N seeds, N configurations
+
+## Evaluation Types (must be declared)
+
+| Type | Label | What it means | Claim ceiling |
+|------|-------|---------------|---------------|
+| Real GT | `real_gt` | Dataset-provided ground truth | Full performance claims |
+| Synthetic proxy | `synthetic_proxy` | Model-generated reference | "Proxy consistency" only |
+| Self-supervised | `self_supervised_proxy` | No GT by design | Relative improvement only |
+| Simulation | `simulation_only` | Simulated environment | "In simulation" qualifier |
+| Human eval | `human_eval` | Human judges | Subject to inter-rater stats |
+
+## Who Checks
+
+The **reviewer model** (different family from executor) performs integrity checks via `/experiment-audit`. The executor collects file paths; the reviewer reads code and results directly.
+
+**Never let the executor judge its own experiment integrity.**

package/skills/skills-codex/shared-references/external-cadence.md

@@ -0,0 +1,334 @@
+# External Cadence
+
+> **Codex mirror adaptation (normative).** External cadence remains fire-control
+> only. The default fresh Codex reviewer may produce a provisional stop/continue
+> decision, while only a cross-family overlay or deterministic gate records
+> accepted. Replace mainline Codex MCP examples with fresh `spawn_agent` calls;
+> never schedule reviewer verdicts themselves.
+
+External schedulers — `/loop`, `/schedule`, `CronCreate`, and any
+wall-clock "wake me every N minutes" mechanism — decide **WHEN** an
+agent wakes up. They do not, and must not, decide **WHO** judges the
+work or **WHETHER** a result is accepted.
+
+## Core Principle
+
+**External cadence is pure fire-control. It is never a jury.**
+
+A scheduler picks the firing moment. It points the agent at a task at a
+chosen time. It has no opinion on correctness, quality, novelty, or
+publishability, and it must never silently re-spawn an agent or drop a
+verdict step in order to stay cheap or finish faster.
+
+Rule of thumb: **cadence can DRIVE; it cannot ACQUIT.** This is the
+fire-control corollary of the acceptance-gate rule
+(`acceptance-gate.md`): a goal/loop may keep an agent going, but the
+STOP/ACCEPT decision still belongs to whoever the acceptance gate
+assigns it to — fresh Codex quality/correctness verdicts are provisional;
+only a cross-family overlay or deterministic verifier is accepted
+(`reviewer-independence.md`).
+
+## Known failure mode (why this doc exists)
+
+External cadence is genuinely useful for one shape of work — waiting on
+the external world — and genuinely harmful for another — wrapping
+ARIS's own internal semantic loops. The two look superficially similar
+("run this skill again later"), so people reach for `/loop` on both. The
+harmful case has a specific pathology:
+
+- **Verdict re-run on a wall-clock timer.** Wrapping
+  `/auto-review-loop` in `/loop 30m` does not produce 30-minutes-better
+  review. It re-runs a verdict-bearing skill on a clock that has nothing
+  to do with whether the artifact changed. Zero new signal, full token
+  cost.
+- **Thread discontinuity.** ARIS's multi-round review skills carry state
+  across rounds in the reviewer's own thread: `codex-reply` reuses the
+  round-1 `threadId` and the accumulated `REVIEWER_MEMORY` so the
+  reviewer can check resolution against its *own* prior critique
+  (`reviewer-independence.md`, Exception). An external `/loop` re-enters
+  the skill from the top each tick, starting a *fresh* `threadId`. The
+  reviewer loses its memory of what it already flagged; "did you fix
+  round 1's gap?" becomes unanswerable.
+- **Duplicated scheduling.** `/experiment-queue` already runs a
+  detached server-side scheduler that polls job status every 60s and
+  enforces `depends_on`. Wrapping the queue skill in an external poll
+  loop duplicates that scheduler on a second, uncoordinated clock and
+  invites wave-transition races the queue was built to prevent.
+
+The fix is a clean split: external cadence for **external-world-wait**,
+never for **internal semantic loops**.
+
+## The distinction
+
+| | External-world-wait (ADDITIVE) | Internal semantic loop (HARMFUL to wrap) |
+|---|---|---|
+| What it waits on | A fact in the outside world: job done, metric logged, file landed | A judgment the agent itself produces |
+| What advances it | Reality changing (GPU frees, epoch logs, PDF compiles) | A model emitting a verdict |
+| Owns its own loop? | No — without cadence a Claude session blocks on `sleep` | Yes — the skill already iterates internally, carrying its own round-to-round state (a reviewer thread, or fed-forward summaries) |
+| Cadence replaces | A blocking session burning context on a wait | Nothing — it only re-spawns and re-judges |
+| Acceptance gate | Machine-checkable existence/completion (safe same-model) | Quality/correctness (base Codex = provisional; overlay/deterministic = accepted) |
+
+One-liner: **schedule the wait, never the verdict.**
+
+## ADDITIVE cases (external-world-wait shape)
+
+These replace a Claude session that would otherwise sit `sleep`-ing on
+an external event. The cadence is the *only* thing the agent is waiting
+for; no semantic judgment is being re-run. ARIS already validated this
+pattern in production.
+
+- **GPU / experiment job completion polling.**
+  `/monitor-experiment` + `/check-gpu` on a cadence: "is the job done?
+  are the GPUs still busy?" The agent wakes, reads status, and either
+  reports done or sleeps again. The thing it waits on (job exit, GPU
+  free) is external and machine-checkable.
+- **WandB anomaly checks.** `/training-check` is *already* cron-wired:
+  its SKILL.md sets itself up via `CronCreate` ("do not ask the user
+  whether to set it up — just set it") to read WandB metrics every N
+  minutes and catch NaN / divergence / idle GPUs early. The cadence
+  exists so the agent does not have to hold a session open for the whole
+  training run.
+- **Experiment-queue progression visibility.** Periodically surfacing
+  *where the queue is* (N done / N running / N pending) so a human can
+  watch overnight progress. Read-only visibility — see the fence below
+  on not re-polling the queue's own scheduler.
+- **Overnight `research-pipeline` heartbeat.** A non-judgmental wake
+  that checks whether the current phase is still advancing and, if a
+  phase has stalled, nudges it forward. Heartbeat only — see the
+  overnight-pipeline rule below.
+- **Daily literature watch.** A once-a-day `/research-lit` or
+  `/deepxiv` sweep for new arXiv papers in a tracked direction. The
+  external fact is "the world published something new today"; the
+  cadence just sets the polling rhythm.
+
+ARIS's own `tools/watchdog.py` makes the additive shape explicit: it
+aggregates per-task status into a `summary.txt` whose header documents
+it as a "one-line-per-task summary for CronCreate polling." The
+artifact is built *so that* an external low-frequency poller can read
+completion state cheaply, without holding a session open.
+
+### Why these are safe same-model
+
+In every additive case the acceptance gate is **execution-completeness**
+— exit code, file exists, N jobs ran, metric logged, PDF compiled. Those
+are machine-checkable, so the polling agent may judge them itself
+(`acceptance-gate.md`: "self-judging EXECUTION-completeness is safe
+same-model"). The cadence never touches a quality/correctness verdict.
+
+## NOISE / HARMFUL cases (wrapping internal semantic loops)
+
+- **`/loop` around `/auto-review-loop`.** The auto-review loop *is*
+  already a loop: review → implement fix → re-review, with the reviewer
+  holding round-to-round memory in one `threadId`. Wrapping it in an
+  external timer breaks that continuity (a fresh `threadId` per tick,
+  `REVIEWER_MEMORY` reset) and fires a verdict on wall-clock time
+  instead of on artifact change. Pure noise.
+- **Polling `/experiment-queue` on a timer.** Duplicates the queue's
+  own 60s server-side scheduler on a second clock, racing its
+  wave-transition logic. Use the queue's status output for visibility;
+  do not run a competing poll loop.
+- **Re-asking an agent to "improve the paper" on a timer.** Quality
+  does not improve on a schedule. A timed "improve again" with no new
+  review signal is token burn — and if the loop also *accepts* its own
+  output to decide whether to stop, it has crossed from fire-control
+  into self-acquittal, which the acceptance gate forbids.
+
+## The fence: do NOT wrap these in external cadence
+
+Any **verdict-bearing** skill — one whose output is a judgment of
+quality, correctness, support, novelty, or satisfaction — must run on
+its own internal cadence with its own round-to-round state (a persistent
+reviewer thread, or prior-round summaries fed forward — whichever the skill
+uses), and must terminate through its recorded reviewer route. In the base
+mirror that route is provisional; overlays/deterministic verifiers are accepted. Never put one inside
+`/loop`, `/schedule`, or `CronCreate`:
+
+- `/auto-review-loop` — already loops internally; reviewer carries
+  round-to-round memory in one `threadId` (`codex-reply`)
+- `/auto-review-loop-llm`, `/auto-review-loop-minimax` — same loop, alternate
+  reviewer backend; same internal round cadence (each round's prior-round
+  summary is fed into the next prompt — a stateless per-round API call, not a
+  shared thread, but still verdict-bearing and self-iterating)
+- `/auto-paper-improvement-loop` — review → fix → recompile loop with its own
+  round structure and a fresh-reviewer bias guard each round (no `codex-reply`)
+- `/research-review` — produces a traced review verdict (provisional in base Codex)
+- `/result-to-claim` — judges whether results support a claim
+- `/experiment-audit` — judges experiment integrity
+- `/paper-claim-audit` — judges paper-to-evidence fidelity
+- `/citation-audit` — judges bibliographic correctness
+- `/proof-checker` — judges proof validity across rounds
+- `/kill-argument` — adversarial accept/reject verdict
+
+If you find yourself wanting to schedule one of these, the thing you
+actually want to schedule is the *external wait that precedes it* (job
+done → then audit once), not the verdict itself.
+
+> **Adjacent but distinct — `/dse-loop`.** It also loops internally, so do
+> not wrap it in external cadence either, but for a *different* reason: its
+> stop gate is an **objective machine-checkable metric** ("objective met or
+> timeout"), which is Type-A, not a quality verdict — so it is not a
+> self-acquittal hazard. The reason not to wrap it is **scheduler
+> duplication** (component #4 below), the same reason as `/experiment-queue`,
+> not the verdict fence. Its own objective gate is a safe same-model
+> self-termination (`acceptance-gate.md`).
+
+## The affordance: natural external-wait surfaces
+
+These are the surfaces external cadence is *for*. They wait on the
+outside world and self-judge only machine-checkable completion:
+
+- `/monitor-experiment` — poll for job completion / progress
+- `/check-gpu` — poll for GPU availability and running processes
+- `/experiment-queue` — **visibility only** (report position); never a
+  re-poll that competes with its own scheduler
+- overnight `/research-pipeline` — a **non-judgmental heartbeat + nudge**
+  (see next), never a quality gate
+
+## The overnight-pipeline rule
+
+An overnight `research-pipeline` heartbeat may wake on a cadence,
+detect that a phase has **stalled** (no progress since last tick,
+process died, waiting on a freed resource), and **nudge** it forward —
+unblock a stuck step, restart a dropped job, prod a phase to continue
+("搞快点"). That is fire-control: it changes *when/whether work
+resumes*, not *whether work is good*.
+
+The heartbeat must **NEVER** become a quality gate. It may not decide
+that a paper is good enough, that a proof holds, that a claim is
+supported, or that a review is satisfied. Every such verdict stays on
+its skill's own internal cadence and terminates in its recorded reviewer route
+(`acceptance-gate.md`). The nudge keeps the pipeline moving; it does not
+acquit the work the pipeline produces.
+
+One-liner: **a heartbeat may say "keep going," never "good enough."**
+
+## Loop self-heartbeat + watchdog liveness (catch a silent death)
+
+A `/loop` or `CronCreate` heartbeat is parasitic on a living session; if it dies
+(context compaction, session close) nothing notices. Two-part convention:
+
+1. **Write a heartbeat first.** As the FIRST action of every iteration, rewrite
+   (or `touch`) the loop's state file (`*_STATE.json` / `run_state.json` / a tiny
+   `last_seen` file) so its mtime advances each tick *before* any work that might hang.
+2. **Register it with the watchdog** at startup, and **unregister on completion**:
+   ```bash
+   python3 tools/watchdog.py --register      '{"name":"<run_id>","type":"loop","state_file":"<the heartbeat file>","stale_after_seconds":21600}'
+   # on completion: python3 tools/watchdog.py --unregister "<run_id>"
+   ```
+   `stale_after_seconds` is the loop's OWN tolerance — set it to **comfortably exceed
+   the longest single iteration/operation** (≈ a few × the tick interval), **never** the
+   watchdog poll interval. The watchdog writes **STALE** to `summary.txt` + `alerts.log`
+   (which your poll already reads) when the file's mtime is older than that; a finished
+   loop shows **COMPLETED** (if its state carries a terminal `status`) or should be
+   unregistered. **It only DETECTS** — it never restarts the loop or re-runs a
+   verdict-bearing skill; recovery stays a human/cron decision, per the fence above.
+
+## Stall detection & forced structural pivot
+
+An overnight loop can spin: each iteration tries a near-variant of the last and gets
+diminishing returns. Detect it mechanically and force a *structural* change — not harder
+tuning of the same frame.
+
+- **Count, don't vibe.** Each iteration, record the number of NEW findings (concrete
+  added entries — new evidence, a falsified hypothesis, a candidate direction — *not* a
+  subjective "valuable result"). Resolve the helper via the canonical chain
+  (integration-contract §2): `.aris/tools/iteration_log.py` → `tools/iteration_log.py` →
+  `$ARIS_REPO/tools/iteration_log.py` → `$ARIS_REPO/tools/iteration_log.py` via
+  `~/.aris/repo` (warn-and-skip if unresolved), then
+  `python3 "$ITER_LOG" note <root> <run_id> <phase> <new_findings> [--direction "..."]`.
+  Consecutive zero-finding iterations accumulate a `stale_count` in
+  `.aris/runs/<run_id>.iterations.jsonl` — a sidecar that does **not** touch run_state's
+  done/accepted state.
+- **Forced pivot ladder** (the heartbeat reads the returned `pivot`):
+  - `stale_count >= 2` → **pivot structure, not tactics**: change a structural constraint
+    (frame / objective / data / representation), not a tactical parameter, and pick a
+    direction that differs from every one already tried.
+  - `stale_count >= 4` → **escalate to a human** (flag for attention; stop nudging blindly).
+- **Direction diversity.** Before a re-generation, read the tried directions (research-wiki
+  Failed Ideas + the iteration ledger) and reject a candidate too close to one already tried.
+
+This is a Type-A signal — it counts findings and changes *direction*, it never *judges
+quality* ("keep going / change direction," never "good enough"; quality stays with the
+recorded reviewer route, acceptance-gate.md). Why structure over tactics: when a task stalls
+repeatedly inside one frame, the decisive gain comes from correcting the frame itself, not
+from tuning parameters harder within it.
+
+## Let a broken attempt restart, not just patch
+
+The stall ladder above pivots *direction*; this section is the level below it — a single
+implementation/debug attempt (a build, a training script, an eval harness) that keeps
+failing while the loop is still running. The repo's historical convention was "patch N
+times, then stop and report to a human." That misroutes the escalation: a broken build is
+squarely the executor's job, and the missing move is the RESTART.
+
+- **Discard-and-reimplement is a peer move to another patch, not a last resort.** After
+  1–2 targeted patches fail on the same failure, rewriting the failing piece cleanly from
+  the contract/plan is usually cheaper and more reliable than a third patch on top of two
+  wrong ones — patched-code archaeology is how attempts rot. Treat "delete the attempt
+  and rebuild from the spec" as a normal option at every retry decision, and prefer it
+  once patches start stacking.
+- **Escalate to a human only when the CONTRACT is in question** — the plan/spec is
+  missing, ambiguous, or looks wrong — not merely because the current attempt is broken.
+  "The build is broken" is the executor's problem; "the plan may be wrong" is the human's.
+- **Hard boundary — what a restart may delete.** Only the current attempt's own
+  code/scaffolding (scripts it wrote, configs it generated, its build artifacts). NEVER
+  deletable in a restart: the contract/plan (`research_contract.md`,
+  `EXPERIMENT_PLAN.md`, `PAPER_PLAN.md`), progress ledgers (`EXPERIMENT_TRACKER.md`,
+  iteration/bottleneck ledgers, `*_STATE.json`, `.aris/traces/`), collected data, and
+  completed results. The restart rebuilds the code FROM those files; deleting them
+  defeats the restart. When in doubt whether a path is "attempt" or "state," it is state
+  — keep it.
+- **Restart is bounded like any other move.** A restart consumes a retry-budget slot; two
+  clean reimplements failing the SAME way means the failure is probably in the contract
+  or the environment — which IS the human-escalation trigger above.
+
+## Required components (when you add external cadence to a skill)
+
+1. **Waits on an external fact, not a self-verdict.** State the fact in
+   one observable line: "job exit code present," "epoch logged to
+   WandB," "PDF exists." If the thing being waited on is a model's
+   judgment, cadence is the wrong tool.
+2. **No verdict in the loop body.** The scheduled body may *report*
+   status and *trigger the next external step*; it may not run a
+   verdict-bearing skill (see the fence) as part of deciding whether to
+   continue.
+3. **Self-judges only machine-checkable completion.** The wake's
+   accept/sleep decision must rest on exit code / file existence / count
+   — never on quality or correctness (`acceptance-gate.md`).
+4. **Does not duplicate an existing internal scheduler.** If the target
+   already runs its own loop or server-side poller (auto-review-loop,
+   experiment-queue), do not wrap it — use its status output.
+5. **Preserves thread continuity for any judgment it precedes.** If the
+   external wait ends in a verdict step, that verdict step runs *once*,
+   in its own thread, after the wait clears — not re-entered per tick.
+6. **Degrades gracefully when no scheduler exists.** External cadence is
+   additive runtime sugar, never load-bearing. On a runtime with no
+   `/loop` / `CronCreate`, the same work still terminates correctly via
+   a blocking poll or a manual re-invocation; the reviewer assurance class at
+   the end is identical either way (`fan-out-pattern.md`).
+
+## Autonomous-mode discipline (when the human checkpoint is off)
+
+When a skill runs with its human-checkpoint toggle OFF (e.g. `AUTO_PROCEED=true`) or under
+an external heartbeat, it must not stall by ending on a question. Resolve a routine
+ambiguity yourself, act, and log the decision and its reasoning (a `level=decision` log
+line) so the choice is auditable — "ready means execute": finishing preparation and then
+asking "should I proceed?" is the stall this rule forbids.
+
+This does **not** override an *explicit* human gate. A checkpoint the skill declares as
+load-bearing — a missing venue/target, a patent/submission step, anything marked as
+requiring sign-off — still stops and waits. If you are unsure whether a gate is explicit, treat it as explicit and stop. Autonomy removes *needless* pauses, not
+deliberate ones; and it never lets the loop self-acquit an accepted quality verdict (that
+stays with the recorded reviewer route, see [`acceptance-gate.md`](acceptance-gate.md)).
+
+## Cross-references
+
+- `acceptance-gate.md` — who is allowed to ACCEPT. Cadence drives;
+  it does not acquit. The overnight nudge is bound by this rule.
+- `fan-out-pattern.md` — fan-out (and cadence) are runtime accelerants
+  for a prompt-level pattern; both must degrade gracefully and preserve the
+  same reviewer assurance class.
+- `reviewer-independence.md` — why wrapping a multi-round review in an
+  external timer breaks reviewer thread/memory continuity.
+- `experiment-integrity.md` — the executor never judges its own
+  experiment; a scheduled poll never upgrades to an integrity verdict.