Research run

research-run

Purpose

/research-run executes an existing Package one Experiment at a time. It starts only after Project, Direction, Experiment, and Package records exist in management state. If one is missing, the command returns a handoff to the skill that owns it.

Continue until an evidence-backed terminal result, a named decision, or a concrete external blocker with a next action. Never invoke git.

Authority boundary

Management state lives in .research/state/research.sqlite3; Run measurements live under .research/experiments/. JSONL and interface files are exports. research-run does not read them; a missing interface does not block execution.

research-run may:

• query the selected Package, Experiment, open Runs, Decisions, Rules, and evidence;
• dispatch implementation, review, launch, monitoring, and verification work;
• launch or inspect a Run through lib.experiments;
• emit commands for research-op;
• reconcile experiment callbacks with research-op --op scan-events.

It may not:

• create or revise Project, Direction, or Experiment intent;
• materialize a Package;
• append management events directly;
• treat generated HTML or JavaScript as state;
• copy a measured value into an Experiment gate.

Admission and dispatch use ResearchPaths and StateQuery; Run operations use lib.experiments and research-op. All commands share one workspace and optional --research-root.

Admission

Run admission checks structured state in this order:

State	Meaning	Handoff
NO_PROJECT	no active Project	/research-onboard
NO_DIRECTION	no active Direction	/research-brainstorm
NO_EXPERIMENT	no Experiment belongs to the active Direction	/research-scope
NO_PACKAGE	no Package materializes the Direction and Experiment	/research-package from-scope <direction-id>
NOT_READY	Package exists but readiness has not passed	run readiness checks
READY	the selected Experiment can enter the execution loop	continue

Use:

import sys

sys.path.insert(0, "skills/research-run/scripts")
import admission

state = admission.detect_admission_state(workspace, pkg_id=package_id)
result = admission.run_front_door(
    workspace,
    pkg_id=package_id,
    readiness_ok=True,
    role_sequence=roles,
    adapters=adapters,
)

The source directory is not a Python package in every installation, so script callers may import it by adding skills/research-run/scripts to sys.path, as the local tests do.

Admission returns source_seq and source_hash. Keep both on every dispatched role report. A report from an older state snapshot is rejected.

The interface is deliberately absent from this state machine. Do not add an interface-init handoff to the run path.

Procedure

1. Read bounded context

Read only the selected Package context:

python3 skills/research-op/scripts/research_op.py \
  context <package-id> --experiment <experiment-id> --action launch \
  --workspace . --research-root .research

For a precise record or history:

python3 skills/research-op/scripts/research_op.py \
  show experiment '<package-id>::<experiment-id>' \
  --workspace . --research-root .research

python3 skills/research-op/scripts/research_op.py \
  history 'package/<package-id>' \
  --workspace . --research-root .research

Context is an in-memory projection. Do not persist a package-level context pack. The launcher freezes the exact input used by a Run in that Run's context.json.

2. Select one Experiment

Choose a Package-owned Experiment whose dependencies and status permit execution. Read its spec directly from state. The minimum executable spec contains:

• purpose;
• config_ref;
• gate.

Do not infer a missing field from page order, filenames, or another Experiment.

Package.executionLease.mode controls interaction. USER_GUIDED pauses at human-only or high-risk boundaries; AUTONOMOUS resolves in-charter execution and Plan changes. Neither mode changes the Project charter, verifier independence, budget authority, destructive/external authority, or terminal outcome.

3. Build the workflow snapshot

driver.load_workflow_snapshot(paths, package_id) reads:

• Package lifecycle, phase, blocker, and version;
• Package-owned Experiment statuses;
• management-open Runs;
• each Run's canonical status.json.

Pass that snapshot to:

node workflow.ts next --json '<snapshot>'

The workflow ticket chooses launch, monitoring, result analysis, repair, plan handoff, or a user decision. Dashboard server health is informational for execution. Repairing the human interface must not stop a healthy Run.

4. Apply research-op envelopes

Every management change is an envelope:

{
  "op": "update",
  "target": "experiments-status",
  "payload": {"id": "P1", "to": "ACTIVE"},
  "idempotency_key": "run:P1:active"
}

Validate it with driver.validate_mutation(). Compile it with driver.research_op_argv(paths, package_id, envelope), then run the returned command. Do not write state files yourself.

If research-op rejects the command, use its rule and detail fields to repair the input or select the correct handoff. Do not patch a projection to hide the rejection.

5. Keep Implementation and Tracker current

Materialize each Change plan before its first code edit. After every logical edit batch, synchronize its code-location predicates:

python3 skills/research-run/scripts/implementation_status.py sync \
  --workspace . --research-root .research \
  --package <package-id>

Run declared TDD checks through the same helper; it records PASS or FAIL against the current dependency fingerprint:

python3 skills/research-run/scripts/implementation_status.py verify \
  --workspace . --research-root .research \
  --package <package-id>

If a dependency changes after a passing check, the next sync marks that check STALE and unchecks it. Before implementation review or launch readiness, run implementation_status.py check; it fails unless every planned code location and verification is currently PASS. Do not add a watcher, edit checkbox state by hand, or infer completion from the generated page.

After every completed To-Do task, update its owner before selecting the next task: synchronize and verify a Change, or reconcile the Run with scan-events. Tracker then derives the same status automatically. Never write a separate Tracker row, completion boolean, or current-task marker.

For a configuration-only replacement of a running Experiment, read Replacement Run cutover.

6. Check readiness and launch

Before launch, verify:

• Package lifecycle is ACTIVE;
• Package phase is READY_TO_LAUNCH;
• Experiment status is READY;
• the Experiment spec is complete;
• the Package has an open Scope Execution Lease that includes the Experiment; imported Packages without a lease require the legacy user launch acknowledgement;
• any requested GPU allocation is open and bound to this Package and Experiment.

The launcher enforces these conditions again:

python3 lib/experiments/launch.py \
  --workspace . \
  --research-root .research \
  --pkg <package-id> \
  --exp <experiment-id> \
  --tmux-session <name> \
  -- bash <command>

Use --foreground for a short command. Long runs should use the default tmux transport.

7. Monitor and reconcile

List management-open Runs:

python3 lib/experiments/report.py \
  --workspace . --research-root .research --open

Inspect one Run with:

python3 lib/experiments/report.py \
  --workspace . --research-root .research \
  --run .research/experiments/<package>/<experiment>/<run>

Use status.json, events.jsonl, metrics.jsonl, and log.txt from that Run. Raw tmux scrollback is only a debugging aid.

At every check and after completion:

python3 skills/research-op/scripts/research_op.py \
  --workspace . --research-root .research \
  --pkg <package-id> --op scan-events --payload '{}'

This repairs lost launch or terminal callbacks without introducing a second live index.

8. Extract and finalize results

For a schema-backed Run, read skills/research-package/references/results-page-pattern.md, extract with python3 -m lib.experiments.result_tables, then finalize with python3 -m lib.experiments.extract and its manifest. Never hand-write tables or replace a finalized result.

9. Verify and route

Read measured values from the verified result.json and its EvidenceRefs. Compare them with the Experiment gate. Record the result through research-op; the verifier must not rewrite the gate. A success route requires a state-backed VERIFIER_VERDICT Decision bound to the finalized Run event, result hash, Experiment scope version, gate, and measured value.

If another Experiment remains, route back to readiness. Otherwise record a terminal Package outcome or the exact blocker. A deferred run should record its continuation as structured state, including the current Experiment, evidence, blocker, and next check time.

Role reports

Reports include role, assigned Scope, source_seq, source_hash, Direction, sourceExperiment, status, evidence, blockers, next action, and mutations. The controller decides; implementation review uses a separate reviewer.

Stop condition

A tick may stop when:

• every completed Run has been reconciled and its evidence is recorded;
• no scan-events action remains pending;
• each open Run has a scheduled next check;
• the Package is terminal, waiting on a named decision, or blocked by a concrete external condition.

Waiting by itself is not a terminal outcome.

The interface can be deleted and rebuilt without changing this procedure.