1#!/usr/bin/env python3
2"""Create and manage file-based research-to-skill runs.
3 
4This runner does not call an LLM. It creates durable artifacts that autonomous
5agents or humans can fill in, then runs deterministic validation.
6"""
7 
8from __future__ import annotations
9 
10import argparse
11import json
12import re
13import shutil
14import subprocess
15import sys
16from datetime import datetime, timezone
17from pathlib import Path
18from typing import Any
19from uuid import uuid4
20 
21 
22ROOT = Path(__file__).resolve().parents[2]
23RESEARCHER = ROOT / "researcher"
24LOCKED_SURFACES = [
25    "researcher/rubrics/content-curation.md",
26    "researcher/rubrics/skill-change.md",
27    "researcher/rubrics/harness-change.md",
28    "researcher/mechanisms/registry.jsonl",
29    ".claude-plugin/marketplace.json",
30    ".plugin/plugin.json",
31    "researcher/scripts/validate_repo.py",
32]
33VALID_CLOSE_STATUS = {"accepted", "rejected", "reference-only", "abandoned"}
34 
35 
36def slugify(value: str) -> str:
37    value = value.lower()
38    value = re.sub(r"[^a-z0-9]+", "-", value)
39    value = re.sub(r"-+", "-", value).strip("-")
40    return value[:64] or "research-run"
41 
42 
43def utc_now() -> str:
44    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
45 
46 
47def load_json(path: Path) -> Any:
48    return json.loads(path.read_text(encoding="utf-8"))
49 
50 
51def write_json(path: Path, data: Any) -> None:
52    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
53 
54 
55def append_jsonl(path: Path, data: Any) -> None:
56    path.parent.mkdir(parents=True, exist_ok=True)
57    with path.open("a", encoding="utf-8") as handle:
58        handle.write(json.dumps(data, sort_keys=True) + "\n")
59 
60 
61def run_relative(run_dir: Path) -> str:
62    return str(run_dir.relative_to(ROOT))
63 
64 
65def state_path(run_dir: Path) -> Path:
66    return run_dir / "run-state.json"
67 
68 
69def initial_state(run_dir: Path, title: str, source_url: str | None) -> dict[str, Any]:
70    timestamp = utc_now()
71    return {
72        "run_id": run_dir.name,
73        "title": title,
74        "source_url": source_url or "",
75        "current_state": "initialized",
76        "close_status": None,
77        "close_reason": None,
78        "locked_surfaces": LOCKED_SURFACES,
79        "editable_surfaces": [
80            f"{run_relative(run_dir)}/sources/",
81            f"{run_relative(run_dir)}/proposals/",
82            f"{run_relative(run_dir)}/reports/",
83            f"{run_relative(run_dir)}/logs/",
84        ],
85        "state_history": [
86            {
87                "state": "initialized",
88                "timestamp": timestamp,
89                "reason": "run initialized",
90                "evidence": run_relative(run_dir),
91            }
92        ],
93        "created_at": timestamp,
94        "updated_at": timestamp,
95    }
96 
97 
98def load_state(run_dir: Path) -> dict[str, Any]:
99    path = state_path(run_dir)
100    if not path.exists():
101        return initial_state(run_dir, run_dir.name, None)
102    return load_json(path)
103 
104 
105def write_state(run_dir: Path, state: dict[str, Any]) -> None:
106    state["updated_at"] = utc_now()
107    write_json(state_path(run_dir), state)
108 
109 
110def set_state(run_dir: Path, state_name: str, reason: str, evidence: str = "") -> None:
111    state = load_state(run_dir)
112    state["current_state"] = state_name
113    state.setdefault("state_history", []).append(
114        {
115            "state": state_name,
116            "timestamp": utc_now(),
117            "reason": reason,
118            "evidence": evidence,
119        }
120    )
121    write_state(run_dir, state)
122    append_thread_decision(run_dir, f"state -> {state_name}", reason, evidence, "continue run")
123 
124 
125def append_thread_decision(run_dir: Path, decision: str, reason: str, evidence: str, next_action: str) -> None:
126    thread = run_dir / "THREAD.md"
127    if not thread.exists():
128        return
129    entry = (
130        "\n```text\n"
131        f"{utc_now()} decision: {decision}\n"
132        f"reason: {reason}\n"
133        f"evidence: {evidence}\n"
134        f"next: {next_action}\n"
135        "```\n"
136    )
137    with thread.open("a", encoding="utf-8") as handle:
138        handle.write(entry)
139 
140 
141def create_thread(run_dir: Path, title: str, source_url: str | None) -> None:
142    thread = f"""# Research Thread: {run_dir.name}
143 
144## Mission
145 
146- Objective: {title}
147- Scope: Evaluate candidate sources and produce reviewable skill proposals.
148- Started: {utc_now()}
149- Owner: autonomous-research-loop
150- Current status: active
151 
152## Locked Surfaces
153 
154- `researcher/rubrics/content-curation.md`
155- `researcher/rubrics/skill-change.md`
156- `researcher/rubrics/harness-change.md`
157- `researcher/mechanisms/registry.jsonl`
158- `.claude-plugin/marketplace.json`
159- `.plugin/plugin.json`
160- `researcher/scripts/validate_repo.py`
161- Merge policy: agents may prepare PRs, but human approval is required for push and merge.
162 
163## Editable Surfaces
164 
165- `{run_dir.relative_to(ROOT)}/sources/`
166- `{run_dir.relative_to(ROOT)}/proposals/`
167- `{run_dir.relative_to(ROOT)}/reports/`
168 
169## Source Queue
170 
171| ID | Source | Status | Next Action |
172| --- | --- | --- | --- |
173| S001 | {source_url or 'TBD'} | discovered | evaluate |
174 
175## Decisions
176 
177```text
178T+00:00 decision: run initialized
179reason: file-based research loop created durable state
180evidence: {run_dir.relative_to(ROOT)}
181next: fill source evaluation and skill proposal
182```
183 
184## Experiments And Evaluations
185 
186| ID | Artifact | Rubric | Result | Notes |
187| --- | --- | --- | --- | --- |
188 
189## Open Questions
190 
191- None recorded.
192 
193## Handover Summary
194 
195- Best current candidate: none yet
196- Rejected candidates: none yet
197- Unresolved risks: source evaluation is a draft until rubric fields are completed
198- Files to read first: `THREAD.md`, `sources/evaluations/source-evaluation-draft.json`, `proposals/skill-proposal.md`
199- Next concrete action: retrieve the source and complete content curation
200"""
201    (run_dir / "THREAD.md").write_text(thread, encoding="utf-8")
202 
203 
204def create_source_evaluation(
205    run_dir: Path,
206    title: str,
207    source_url: str,
208    author_or_org: str,
209    source_type: str,
210) -> None:
211    template = load_json(RESEARCHER / "templates" / "source-evaluation.json")
212    template["evaluation_id"] = str(uuid4())
213    template["timestamp"] = utc_now()
214    template["source"].update(
215        {
216            "url": source_url,
217            "title": title,
218            "author_or_org": author_or_org,
219            "published_at": "",
220            "source_type": source_type,
221            "retrieval_status": "partial" if source_url else "failed",
222            "primary_or_secondary": "primary",
223        }
224    )
225    template["decision"].update(
226        {
227            "verdict": "HUMAN_REVIEW",
228            "override_triggered": "null",
229            "confidence": "low",
230            "justification": "Draft scaffold. Complete gates and scoring after retrieval.",
231        }
232    )
233    write_json(run_dir / "sources" / "evaluations" / "source-evaluation-draft.json", template)
234 
235 
236def create_skill_proposal(run_dir: Path, title: str, source_url: str) -> None:
237    proposal = (RESEARCHER / "templates" / "skill-proposal.md").read_text(encoding="utf-8")
238    proposal = proposal.replace("# Skill Proposal: [Short Title]", f"# Skill Proposal: {title}")
239    proposal = proposal.replace("- URL:", f"- URL: {source_url}")
240    proposal = proposal.replace("- Title:", f"- Title: {title}")
241    proposal = proposal.replace("- Retrieval status:", "- Retrieval status: partial")
242    proposal = proposal.replace("- Decision: APPROVE / HUMAN_REVIEW / REJECT", "- Decision: HUMAN_REVIEW")
243    (run_dir / "proposals" / "skill-proposal.md").write_text(proposal, encoding="utf-8")
244    (run_dir / "proposals" / "mechanism-proposal.jsonl").write_text(
245        (RESEARCHER / "templates" / "mechanism-proposal.jsonl").read_text(encoding="utf-8"),
246        encoding="utf-8",
247    )
248 
249 
250def update_queue(run_dir: Path, **updates: Any) -> None:
251    queue = run_dir / "sources" / "queue.jsonl"
252    if not queue.exists():
253        raise FileNotFoundError(f"source queue missing: {queue}")
254    records = [json.loads(line) for line in queue.read_text(encoding="utf-8").splitlines() if line.strip()]
255    if not records:
256        raise ValueError("source queue is empty")
257    records[0].update(updates)
258    queue.write_text("\n".join(json.dumps(record, sort_keys=True) for record in records) + "\n", encoding="utf-8")
259 
260 
261def completed_evaluation(run_dir: Path) -> Path:
262    eval_dir = run_dir / "sources" / "evaluations"
263    completed = sorted(path for path in eval_dir.glob("*.json") if "draft" not in path.stem)
264    if not completed:
265        raise FileNotFoundError("completed source evaluation missing")
266    return completed[0]
267 
268 
269def proposal_file(run_dir: Path) -> Path:
270    path = run_dir / "proposals" / "skill-proposal.md"
271    if not path.exists():
272        raise FileNotFoundError(f"skill proposal missing: {path}")
273    return path
274 
275 
276def retrieve_source(args: argparse.Namespace) -> int:
277    run_dir = args.run_dir.resolve()
278    raw_dir = run_dir / "sources" / "evidence" / "raw"
279    raw_dir.mkdir(parents=True, exist_ok=True)
280    copied: list[str] = []
281    for source in args.file or []:
282        target = raw_dir / source.name
283        shutil.copy2(source, target)
284        copied.append(str(target.relative_to(ROOT)))
285    update_queue(
286        run_dir,
287        retrieval_status="retrieved",
288        retrieved_at=utc_now(),
289        raw_evidence=copied,
290        retrieval_notes=args.notes,
291    )
292    set_state(
293        run_dir,
294        "retrieved",
295        "source evidence retrieved",
296        ", ".join(copied) if copied else "manual retrieval recorded",
297    )
298    return 0
299 
300 
301def mark_evaluated(args: argparse.Namespace) -> int:
302    run_dir = args.run_dir.resolve()
303    eval_path = completed_evaluation(run_dir)
304    data = load_json(eval_path)
305    update_queue(
306        run_dir,
307        retrieval_status=data.get("source", {}).get("retrieval_status", "retrieved"),
308        evaluation_file=str(eval_path.relative_to(ROOT)),
309        evaluation_decision=data.get("decision", {}).get("verdict", ""),
310    )
311    set_state(run_dir, "evaluated", "completed source evaluation recorded", str(eval_path.relative_to(ROOT)))
312    return 0
313 
314 
315def mark_proposed(args: argparse.Namespace) -> int:
316    run_dir = args.run_dir.resolve()
317    path = proposal_file(run_dir)
318    set_state(run_dir, "proposed", "skill proposal recorded", str(path.relative_to(ROOT)))
319    return 0
320 
321 
322def run_novelty(args: argparse.Namespace) -> int:
323    run_dir = args.run_dir.resolve()
324    path = proposal_file(run_dir)
325    result_path = run_dir / "reports" / "novelty-result.json"
326    cmd = [
327        sys.executable,
328        str(RESEARCHER / "scripts" / "novelty_check.py"),
329        "--file",
330        str(path),
331        "--json",
332    ]
333    completed = subprocess.run(cmd, cwd=ROOT, text=True, capture_output=True, check=False)
334    if completed.stdout:
335        result = json.loads(completed.stdout)
336    else:
337        result = {
338            "verdict": "human_review",
339            "error": completed.stderr or "novelty_check.py produced no output",
340        }
341    if args.human_review_rationale:
342        result["human_review_rationale"] = args.human_review_rationale
343    write_json(result_path, result)
344    set_state(run_dir, "novelty_checked", "novelty result recorded", str(result_path.relative_to(ROOT)))
345    return completed.returncode
346 
347 
348def run_run_validator(run_dir: Path) -> int:
349    report_json = run_dir / "reports" / "run-readiness.json"
350    report_md = run_dir / "reports" / "run-readiness.md"
351    cmd = [
352        sys.executable,
353        str(RESEARCHER / "scripts" / "validate_run.py"),
354        "--run-dir",
355        str(run_dir),
356        "--json",
357    ]
358    completed = subprocess.run(cmd, cwd=ROOT, text=True, capture_output=True, check=False)
359    report_json.write_text(completed.stdout or json.dumps({"ok": False, "error": completed.stderr}), encoding="utf-8")
360    try:
361        data = json.loads(completed.stdout)
362        summary = data.get("summary", {})
363        text = (
364            "# Run Readiness Report\n\n"
365            f"Run validation {'passed' if data.get('ok') else 'failed'}: "
366            f"{summary.get('errors', 0)} errors, {summary.get('warnings', 0)} warnings.\n"
367        )
368    except json.JSONDecodeError:
369        text = f"# Run Readiness Report\n\nValidation command failed.\n\n{completed.stderr}\n"
370    report_md.write_text(text, encoding="utf-8")
371    if completed.returncode == 0:
372        set_state(run_dir, "validated", "run readiness validation passed", str(report_json.relative_to(ROOT)))
373    return completed.returncode
374 
375 
376def run_validator(run_dir: Path) -> int:
377    report_json = run_dir / "reports" / "validation-report.json"
378    report_md = run_dir / "reports" / "validation-report.md"
379    cmd = [
380        sys.executable,
381        str(RESEARCHER / "scripts" / "validate_repo.py"),
382        "--root",
383        str(ROOT),
384        "--json",
385    ]
386    completed = subprocess.run(cmd, cwd=ROOT, text=True, capture_output=True, check=False)
387    if completed.stdout:
388        report_json.write_text(completed.stdout, encoding="utf-8")
389    else:
390        report_json.write_text(
391            json.dumps(
392                {
393                    "ok": False,
394                    "summary": {"errors": 1, "warnings": 0, "skill_count": 0},
395                    "findings": [
396                        {
397                            "severity": "error",
398                            "path": "researcher/scripts/validate_repo.py",
399                            "message": completed.stderr or "validator produced no output",
400                        }
401                    ],
402                },
403                indent=2,
404            )
405            + "\n",
406            encoding="utf-8",
407        )
408    summary = "Validation command exited with code " + str(completed.returncode)
409    if completed.stdout:
410        try:
411            data = json.loads(completed.stdout)
412            summary = (
413                f"Validation {'passed' if data.get('ok') else 'failed'}: "
414                f"{data.get('summary', {}).get('errors', 0)} errors, "
415                f"{data.get('summary', {}).get('warnings', 0)} warnings."
416            )
417        except json.JSONDecodeError:
418            pass
419    report_md.write_text(f"# Validation Report\n\n{summary}\n", encoding="utf-8")
420    return completed.returncode
421 
422 
423def write_pr_readiness(args: argparse.Namespace) -> int:
424    run_dir = args.run_dir.resolve()
425    path = run_dir / "reports" / "pr-readiness.md"
426    text = f"""# PR Readiness Notes
427 
428## Summary
429 
430{args.summary}
431 
432## Test Plan
433 
434{args.test_plan}
435 
436## Risks
437 
438{args.risks}
439 
440Merge and push require explicit human approval.
441"""
442    path.write_text(text, encoding="utf-8")
443    set_state(run_dir, "pr_ready", "PR readiness notes recorded", str(path.relative_to(ROOT)))
444    return 0
445 
446 
447def close_run(args: argparse.Namespace) -> int:
448    if args.status not in VALID_CLOSE_STATUS:
449        raise ValueError(f"status must be one of {sorted(VALID_CLOSE_STATUS)}")
450    run_dir = args.run_dir.resolve()
451    closure = {
452        "status": args.status,
453        "reason": args.reason,
454        "closed_at": utc_now(),
455        "reviewed_by": args.reviewed_by,
456    }
457    path = run_dir / "reports" / "closure.json"
458    write_json(path, closure)
459    state = load_state(run_dir)
460    state["current_state"] = "closed"
461    state["close_status"] = args.status
462    state["close_reason"] = args.reason
463    state.setdefault("state_history", []).append(
464        {
465            "state": "closed",
466            "timestamp": utc_now(),
467            "reason": args.reason,
468            "evidence": str(path.relative_to(ROOT)),
469        }
470    )
471    write_state(run_dir, state)
472    append_thread_decision(run_dir, f"closed as {args.status}", args.reason, str(path.relative_to(ROOT)), "stop run")
473    return 0
474 
475 
476def load_jsonl(path: Path) -> list[dict[str, Any]]:
477    if not path.exists():
478        raise FileNotFoundError(f"JSONL file missing: {path}")
479    records: list[dict[str, Any]] = []
480    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
481        if not line.strip():
482            continue
483        try:
484            records.append(json.loads(line))
485        except json.JSONDecodeError as exc:
486            raise ValueError(f"{path}:{line_number} invalid JSONL: {exc}") from exc
487    return records
488 
489 
490def run_readiness_ok(run_dir: Path) -> bool:
491    cmd = [
492        sys.executable,
493        str(RESEARCHER / "scripts" / "validate_run.py"),
494        "--run-dir",
495        str(run_dir),
496        "--json",
497    ]
498    completed = subprocess.run(cmd, cwd=ROOT, text=True, capture_output=True, check=False)
499    if completed.returncode != 0:
500        return False
501    try:
502        return bool(json.loads(completed.stdout).get("ok"))
503    except json.JSONDecodeError:
504        return False
505 
506 
507def promote_mechanisms(args: argparse.Namespace) -> int:
508    if not args.reviewed_by:
509        raise ValueError("--reviewed-by is required for mechanism promotion")
510    run_dir = args.run_dir.resolve()
511    proposal_path = run_dir / "proposals" / "mechanism-proposal.jsonl"
512    proposals = load_jsonl(proposal_path)
513    if not proposals:
514        raise ValueError("mechanism proposal file is empty")
515 
516    registry_path = RESEARCHER / "mechanisms" / "registry.jsonl"
517    accepted_ledger = RESEARCHER / "mechanisms" / "ledgers" / "accepted.jsonl"
518    rejected_ledger = RESEARCHER / "mechanisms" / "ledgers" / "rejected.jsonl"
519    existing_ids = {
520        record.get("mechanism_id")
521        for record in load_jsonl(registry_path)
522        if record.get("mechanism_id")
523    }
524    promoted = 0
525    rejected = 0
526    readiness_ok = run_readiness_ok(run_dir)
527 
528    for proposal in proposals:
529        status = proposal.get("status_recommendation")
530        mechanism_id = proposal.get("mechanism_id")
531        if not mechanism_id or mechanism_id == "kebab-case-id":
532            raise ValueError("mechanism proposal contains placeholder mechanism_id")
533        event = {
534            "mechanism_id": mechanism_id,
535            "status": status,
536            "reviewed_by": args.reviewed_by,
537            "run_dir": run_relative(run_dir),
538            "rationale": proposal.get("review_rationale", ""),
539            "timestamp": utc_now(),
540        }
541        if status in {"accepted", "candidate"}:
542            if not readiness_ok and not args.allow_unready:
543                raise ValueError("run readiness must pass before promoting accepted or candidate mechanisms")
544            if mechanism_id in existing_ids:
545                raise ValueError(f"mechanism already exists in registry: {mechanism_id}")
546            registry_entry = {
547                "mechanism_id": mechanism_id,
548                "owning_skill": proposal.get("owning_skill", ""),
549                "status": status,
550                "activation_scenario": proposal.get("activation_scenario", ""),
551                "behavior_change": proposal.get("behavior_change", ""),
552                "evidence": proposal.get("evidence_claim_ids", []),
553                "failure_modes": proposal.get("failure_modes", []),
554            }
555            append_jsonl(registry_path, registry_entry)
556            append_jsonl(accepted_ledger, event)
557            existing_ids.add(mechanism_id)
558            promoted += 1
559        elif status == "rejected":
560            append_jsonl(rejected_ledger, event)
561            rejected += 1
562        else:
563            raise ValueError("status_recommendation must be accepted, candidate, or rejected")
564 
565    set_state(
566        run_dir,
567        "validated" if promoted else "closed",
568        f"mechanism promotion complete: {promoted} promoted, {rejected} rejected",
569        str(proposal_path.relative_to(ROOT)),
570    )
571    return 0
572 
573 
574def create_run(args: argparse.Namespace) -> Path:
575    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
576    run_dir = RESEARCHER / "runs" / f"{timestamp}-{slugify(args.title)}"
577    for child in [
578        run_dir / "sources" / "evaluations",
579        run_dir / "proposals",
580        run_dir / "reports",
581        run_dir / "logs",
582        run_dir / "sources" / "evidence" / "raw",
583    ]:
584        child.mkdir(parents=True, exist_ok=False)
585 
586    source_record = {
587        "id": "S001",
588        "url": args.url,
589        "title": args.title,
590        "author_or_org": args.author_or_org,
591        "source_type": args.source_type,
592        "retrieval_status": "partial" if args.url else "failed",
593        "candidate_reason": args.reason,
594        "created_at": utc_now(),
595    }
596    (run_dir / "sources" / "queue.jsonl").write_text(
597        json.dumps(source_record) + "\n",
598        encoding="utf-8",
599    )
600    create_thread(run_dir, args.title, args.url)
601    write_state(run_dir, initial_state(run_dir, args.title, args.url))
602    create_source_evaluation(run_dir, args.title, args.url, args.author_or_org, args.source_type)
603    create_skill_proposal(run_dir, args.title, args.url)
604    run_validator(run_dir)
605    return run_dir
606 
607 
608def main() -> int:
609    parser = argparse.ArgumentParser(description="Create durable research-to-skill run artifacts")
610    sub = parser.add_subparsers(dest="command", required=True)
611 
612    init = sub.add_parser("init", help="initialize a research run")
613    init.add_argument("--title", required=True, help="candidate source or run title")
614    init.add_argument("--url", default="", help="candidate source URL")
615    init.add_argument("--author-or-org", default="", help="source author or organization")
616    init.add_argument(
617        "--source-type",
618        default="other",
619        choices=["paper", "engineering_blog", "documentation", "benchmark", "code", "talk", "other"],
620    )
621    init.add_argument("--reason", default="", help="why this source/run matters")
622 
623    validate = sub.add_parser("validate", help="run deterministic repo validation")
624    validate.add_argument("--run-dir", type=Path, help="optional run directory to store report")
625 
626    retrieve = sub.add_parser("retrieve", help="record retrieved source evidence for a run")
627    retrieve.add_argument("--run-dir", type=Path, required=True)
628    retrieve.add_argument("--file", type=Path, action="append", help="raw evidence file to copy into the run")
629    retrieve.add_argument("--notes", default="", help="retrieval notes")
630 
631    evaluate = sub.add_parser("evaluate", help="mark a run as source-evaluated")
632    evaluate.add_argument("--run-dir", type=Path, required=True)
633 
634    propose = sub.add_parser("propose", help="mark a run as having a proposal")
635    propose.add_argument("--run-dir", type=Path, required=True)
636 
637    novelty = sub.add_parser("novelty", help="run novelty check and persist result")
638    novelty.add_argument("--run-dir", type=Path, required=True)
639    novelty.add_argument("--human-review-rationale", default="")
640 
641    validate_run = sub.add_parser("validate-run", help="validate run publish readiness")
642    validate_run.add_argument("--run-dir", type=Path, required=True)
643 
644    pr_ready = sub.add_parser("pr-ready", help="write PR readiness notes")
645    pr_ready.add_argument("--run-dir", type=Path, required=True)
646    pr_ready.add_argument("--summary", required=True)
647    pr_ready.add_argument("--test-plan", required=True)
648    pr_ready.add_argument("--risks", required=True)
649 
650    close = sub.add_parser("close", help="close a run with rationale")
651    close.add_argument("--run-dir", type=Path, required=True)
652    close.add_argument("--status", required=True, choices=sorted(VALID_CLOSE_STATUS))
653    close.add_argument("--reason", required=True)
654    close.add_argument("--reviewed-by", default="")
655 
656    promote = sub.add_parser("promote-mechanisms", help="promote reviewed mechanism proposals")
657    promote.add_argument("--run-dir", type=Path, required=True)
658    promote.add_argument("--reviewed-by", required=True)
659    promote.add_argument(
660        "--allow-unready",
661        action="store_true",
662        help="allow promotion before run readiness; intended only for bootstrapping fixtures",
663    )
664 
665    args = parser.parse_args()
666    if args.command == "init":
667        run_dir = create_run(args)
668        print(run_dir.relative_to(ROOT))
669        return 0
670    if args.command == "validate":
671        if args.run_dir:
672            (args.run_dir / "reports").mkdir(parents=True, exist_ok=True)
673            return run_validator(args.run_dir)
674        cmd = [sys.executable, str(RESEARCHER / "scripts" / "validate_repo.py")]
675        return subprocess.run(cmd, cwd=ROOT, check=False).returncode
676    if args.command == "retrieve":
677        return retrieve_source(args)
678    if args.command == "evaluate":
679        return mark_evaluated(args)
680    if args.command == "propose":
681        return mark_proposed(args)
682    if args.command == "novelty":
683        return run_novelty(args)
684    if args.command == "validate-run":
685        return run_run_validator(args.run_dir.resolve())
686    if args.command == "pr-ready":
687        return write_pr_readiness(args)
688    if args.command == "close":
689        return close_run(args)
690    if args.command == "promote-mechanisms":
691        return promote_mechanisms(args)
692    return 1
693 
694 
695if __name__ == "__main__":
696    sys.exit(main())
697