1# Researcher Runs
2 
3Each run is one trip through the research-to-skill state machine. Run directories are runtime artifacts; only the seed run is committed as a worked example.
4 
5## Layout
6 
7```
8researcher/runs/<timestamp>-<slug>/
9  run-state.json              # state machine, locked surfaces, transition history
10  THREAD.md                   # human-readable thread log
11  sources/
12    queue.jsonl               # source records for this run
13    evaluations/              # source-evaluation JSON (drafts allowed, completed required for publish)
14    evidence/
15      retrieval.md            # pointer log of retrieved evidence
16      raw/                    # raw fetched HTML/JSON
17  proposals/
18    skill-proposal.md         # proposal targeting a specific skill change
19    mechanism-proposal.jsonl  # candidate mechanisms for the registry
20  reports/
21    validation-report.json    # repo-level validation snapshot at init time
22    validation-report.md      # human summary
23    novelty-result.json       # latest novelty check (created by `research_loop.py novelty`)
24    pr-readiness.md           # PR summary, test plan, risks (created by `pr-ready`)
25    closure.json              # set by `close`
26    run-readiness.{json,md}   # set by `validate-run`
27  logs/
28```
29 
30## State machine
31 
32```
33initialized -> retrieved -> evaluated -> proposed -> novelty_checked -> validated -> pr_ready -> closed
34```
35 
36Use `researcher/scripts/research_loop.py` subcommands rather than editing `run-state.json` directly:
37 
38```bash
39python3 researcher/scripts/research_loop.py init --title "..." --url "..."
40python3 researcher/scripts/research_loop.py retrieve --run-dir <run> --file <evidence>
41python3 researcher/scripts/research_loop.py evaluate --run-dir <run>
42python3 researcher/scripts/research_loop.py propose --run-dir <run>
43python3 researcher/scripts/research_loop.py novelty --run-dir <run>
44python3 researcher/scripts/research_loop.py validate-run --run-dir <run>
45python3 researcher/scripts/research_loop.py pr-ready --run-dir <run> --summary <text> --test-plan <text> --risks <text>
46python3 researcher/scripts/research_loop.py close --run-dir <run> --status reference-only --reason <text> --reviewed-by <handle>
47```
48 
49## What is committed
50 
51Only `researcher/runs/20260515-035228-executable-autonomous-research-frameworks/` is committed. It is the worked example that bootstrapped the harness-engineering skill and the mechanism registry. Its `current_state` is `closed` and `close_status` is `reference-only`.
52 
53All other run directories are local runtime state and are excluded by `.gitignore`. PRs should not introduce new committed runs; if you need a regression fixture, add it under `researcher/fixtures/` instead.
54