Dr Drive Harness

Drive the harness

You are operating a Popperian reasoning harness whose entire epistemology rests on one rule: the typed record is the only admissible evidence. log.jsonl, objects/, progress.jsonl, run-status.json, REPLAY_VALIDATION.json, verify_root — those are evidence. Model prose, including yours, is not. Every section below is an index: it tells you the load-bearing command and WHERE the full authority lives, so you never operate from a half-remembered copy.

1. Session preflight (before anything else)

The cloud container rolls back silently — stale checkout, dead processes, deleted gitignored files. CLAUDE.md's "Environment" section is the authority; the sequence is:

git log --oneline -1                      # stale head? resync:
git fetch origin <branch> && git checkout -B <branch> origin/<branch>
python -c "import deepreason" || pip install -e . --break-system-packages -q
ls experiments/*/env 2>/dev/null          # gitignored credentials survive?

No live launch without a green soak on the launch config: run python -u scripts/cycle_soak.py --case <case> before any ladder launch. It drives the managed path to cycle 8 on the launch configuration's own shape against the deterministic stub, and carries a named assertion for each of the four 2026-08-22 cycle-0-to-2 operational deaths. It has REPRODUCED one of them offline (the reservation-bound seam); the other three are asserted, not demonstrated — read that tranche's RESULTS.md before treating a green soak as full coverage (experiments/2026-08-23-change-cycle-soak-instrument/).

Always python -m pytest, never bare pytest (PATH shim). Credentials are recreated from the operator's handover, never committed — env files are gitignored; check with git check-ignore <path> before writing near them. Commit and push at every phase boundary — work between pushes is work at risk. Then read, in order: CLAUDE.md, the newest experiments/*/RESULTS.md segments, docs/ERRATA.md.

Where the truth lives, in reading order: CLAUDE.md (law) → docs/map/INDEX.md (navigation) → experiments/*/RESULTS.md (what is proven) → docs/ERRATA.md (what was corrected) → each tranche's PARKED.md (what is deliberately not done).

Re-entering mid-tranche needs no conversation history: every tranche is resumable from its committed artifacts alone. Read the tranche dir's CHECKLIST.md State: line, then REQUEST.md/SPEC.md, and continue. The whole fresh-window prompt is one line — "Resume tranche <dir> from its artifacts." If a session cannot resume from the artifacts, the previous session under-committed; record that gap, reconstruct, and commit.

2. Running it — the public lifecycle

The supported product surface (authority: README.md):

deepreason setup                 # one strict provider profile
deepreason qualify --yes         # explicit; tier ladder full/shallow/unqualified
deepreason status [--json]       # readiness + the one next action
                                 # NB: provider readiness, NOT a run's
                                 # outcome — for that, `results` below
deepreason results ROOT-OR-HOME [--json] [--verify]
                                 # read a run's typed results: id, state,
                                 # stop_reason, cycles, tokens vs budget,
                                 # artifact/survivor/frontier counts,
                                 # defended-trial + judge-call counts, the
                                 # STORED verify_root verdict (--verify
                                 # re-derives), amendment epochs, and
                                 # whether the root is amend-ready.
                                 # Read-only; absent facts print as typed
                                 # absences, never omitted. This is the
                                 # ONE retrieval surface — do not go
                                 # hunting through root files for it.
deepreason reason "QUESTION" [--cycles N] [--token-budget N]
deepreason reason "Q" --attach file.pdf        # frozen evidence, dossier digest
deepreason --root ROOT amend --attach f --reshape-question "Q2"
deepreason --root ROOT continue --budget cycles=N
deepreason reason --shallow "Q"  # MiniReason reduced engine
deepreason web                   # loopback-only page over the MCP facade

Facts that bite (authority: CLAUDE.md "Live runs"): qualification caches by subject digest — same home + profile + opt-ins is a ~1s cache hit, any change reruns a ~14-minute battery; qualify opt-ins must match reason opt-ins (--attached-evidence ⇔ --attach); provider reasoning must be EXPLICITLY disabled for ollama when required (unset is not off — the refusal is typed).

3. Running it — live experiment ladders

Ladders are shell scripts (experiments/*/**_run.sh): setup → qualify → reason → audit against a DEEPREASON_HOME. The rules, each learned the expensive way (authority: CLAUDE.md "Live runs"):

• Run identity is deterministic. Same question + config → same run id; a leftover root refuses with RUN_ALREADY_STARTED. Retire by rename (git mv run-<id> <state>-epochN-run-<id>) and COMMIT THE RENAME FIRST. Never edit a committed root — to change the question or add evidence, deepreason amend then continue.
• Launch detached, never foreground: from the ladder's directory, setsid nohup ./<ladder>.sh & disown. Arm the snapshot loop (snapshot_loop.sh) and a monitor on the newest root's progress.jsonl plus the driver log's rc= lines — alert on failure signatures, not just success.
• Judge only typed outcomes: run state, stop_reason, the audit JSON, verify_root, FINDINGS.md. Capability-channel use is stochastic across identical runs — one live miss is inconclusive; the offline regression is the proof.

4. Where to look BEFORE modifying anything

Never scope a change by grepping 125k lines. The map is the navigation layer, and the reading order is fixed:

1. docs/map/INDEX.md — resolve the work to ids (DR-SUB-<pkg>, DR-CON-<concept>, DR-SEAM-<a>-x-<b>).
2. docs/map/INV-frozen-surfaces.md — first, always: five surfaces are not yours to change (state digests, harness event application, replay-validation formats, manifest schemas + validators, qualification subjects). Readers may be fixed; formats may not.
3. If the change spans two things, the seam document BEFORE either subsystem: the file is docs/map/SEAM-<a>-x-<b>.md, sides in alphabetical order. It names the small fraction of each side actually involved. The worked recipe for any seam change is docs/map/REC-change-a-seam.md.
4. docs/map/SCHEMA.md before writing or editing any map document. The map moves in the SAME commit as the code, or it becomes a document that lies.
5. Record the resolved ids in the tranche's first artifact (GOAL.md or REQUEST.md) — every later phase starts from the same map. If the map has no id for something the work touches, that is a finding, not a blocker: say so, and creating the missing document becomes part of the tranche.

Instruments that prove you broke nothing: the full gate (python -m pytest tests/ -q -n 4, 0 failed only) and the root sweep (python tools/root_sweep.py — no committed root's verdict may move). Third instrument, which NO gate runs for you: the wheel smokes (python scripts/wheel_smoke.py; python -u scripts/wheel_operational_smoke.py) — build-and-operate checks over the INSTALLED package. They pin the public surface (console entry points, MCP tool set + schema sha, wheel layout), so any change to that surface updates the pins and re-runs the smoke in the SAME commit, or the instrument rots silently and nothing else will catch it. python tools/docs_verify.py is the same gate for the map — and its --fast mode reuses cached results, so it CANNOT catch a document your src/ change just broke. Iterate with --fast; run the FULL mode at least once before any commit that touches src/.